kubernetes: API docs for job status should clearly explain what fields indicate success or failure

The API docs for jobs are unclear as to what fields a caller would use to determine job success or failure in 1.11 (and we haven’t updated them in a while)

  status:
    conditions:
    - lastProbeTime: 2018-09-15T19:51:27Z
      lastTransitionTime: 2018-09-15T19:51:27Z
      message: Job has reached the specified backoff limit
      reason: BackoffLimitExceeded
      status: "True"
      type: Failed
    failed: 6
    startTime: 2018-09-15T19:46:13Z

$ kubectl explain jobs.status
KIND:     Job
VERSION:  batch/v1

RESOURCE: status <Object>

DESCRIPTION:
     Current status of a job. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status

     JobStatus represents the current state of a Job.

FIELDS:
   active	<integer>
     The number of actively running pods.

   completionTime	<string>
     Represents time when the job was completed. It is not guaranteed to be set
     in happens-before order across separate operations. It is represented in
     RFC3339 form and is in UTC.

   conditions	<[]Object>
     The latest available observations of an object's current state. More info:
     https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/

   failed	<integer>
     The number of pods which reached phase Failed.

   startTime	<string>
     Represents time when the job was acknowledged by the job controller. It is
     not guaranteed to be set in happens-before order across separate
     operations. It is represented in RFC3339 form and is in UTC.

   succeeded	<integer>
     The number of pods which reached phase Succeeded.

A casual reader would infer that completionTime is set when the job fails (but it isn’t). Linking out to the docs is ok, but I shouldn’t have to click through the links to understand how to use the Job object. The Job description and the job status fields should clearly indicate what fields are set in completion states on the job, because that’s 100% of the point of docs. Taking a summary of the jobs-run-to-completion link and putting it in job.status.conditions, job.status, and job would improve the actual utility of our API doc.

We should also do a pass on other objects and make the actual in server docs more useful.

@kubernetes/sig-apps-bugs

About this issue

Original URL
State: closed
Created 6 years ago
Reactions: 27
Comments: 23 (6 by maintainers)

Most upvoted comments

I have to say this issue is still very relevant. As of now, it is very hard to design something around Job Statuses. Anyway to move this forward?

+18

rayrutjes on Dec 24, 2018

So what is the correct way to determine if a job is finished and whether it completed successfully?

andrewmchen on Jun 7, 2019

With regards to:

 conditions	<[]Object>
     The latest available observations of an object's current state. More info:
     https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/

If you actually follow this link and then search on that page for “conditions” you will get exactly zero hits. This is extremely unhelpful.

andrewsav-bt on Apr 24, 2019

I think it not only needs documentation, but also a change: It would be good to have 2 fields (probably needs better names), this way it’s easy and clear when a job is finished and if it failed or not and when (someone can look at failed, succeeded and conditions for details):

finished_time: only set when the job finished (either completely failed or completely finished)
finish_type: ‘failed or completed’

pvanderlinden on Jun 25, 2020

So what is the correct way to determine if a job is finished and whether it completed successfully?

When a Job completes (finished successfully), its .status.completionTime will be set, and Job conditions will have one with type==Complete.

When a Job fails, Job conditions will have one with type==Failed.

janetkuo on Jul 23, 2019