Merge pull request #87919 from SomtochiAma/update-api-docs

Adds additional documentation for job status

api/openapi-spec/swagger.json

@@ -4005,10 +4005,10 @@
         },
         "completionTime": {
           "$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.Time",
-          "description": "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."
+          "description": "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. The completion time is only set when the job finishes successfully."
         },
         "conditions": {
-          "description": "The latest available observations of an object's current state. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
+          "description": "The latest available observations of an object's current state. When a job fails, one of the conditions will have type == \"Failed\". More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
           "items": {
             "$ref": "#/definitions/io.k8s.api.batch.v1.JobCondition"
           },

pkg/apis/batch/types.go

@@ -155,6 +155,7 @@ type JobSpec struct {
 type JobStatus struct {
 
 	// The latest available observations of an object's current state.
+	// When a job fails, one of the conditions will have type == "Failed".
 	// +optional
 	Conditions []JobCondition
 
@@ -167,6 +168,7 @@ type JobStatus struct {
 	// 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.
+	// The completion time is only set when the job finishes successfully.
 	// +optional
 	CompletionTime *metav1.Time
 

staging/src/k8s.io/api/batch/v1/generated.proto

@@ -151,6 +151,7 @@ message JobSpec {
 // JobStatus represents the current state of a Job.
 message JobStatus {
   // The latest available observations of an object's current state.
+  // When a job fails, one of the conditions will have type == "Failed".
   // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
   // +optional
   // +patchMergeKey=type
@@ -166,6 +167,7 @@ message JobStatus {
   // 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.
+  // The completion time is only set when the job finishes successfully.
   // +optional
   optional k8s.io.apimachinery.pkg.apis.meta.v1.Time completionTime = 3;
 

staging/src/k8s.io/api/batch/v1/types.go

@@ -131,6 +131,7 @@ type JobSpec struct {
 // JobStatus represents the current state of a Job.
 type JobStatus struct {
 	// The latest available observations of an object's current state.
+	// When a job fails, one of the conditions will have type == "Failed".
 	// More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
 	// +optional
 	// +patchMergeKey=type
@@ -146,6 +147,7 @@ type JobStatus struct {
 	// 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.
+	// The completion time is only set when the job finishes successfully.
 	// +optional
 	CompletionTime *metav1.Time `json:"completionTime,omitempty" protobuf:"bytes,3,opt,name=completionTime"`
 

staging/src/k8s.io/api/batch/v1/types_swagger_doc_generated.go

@@ -80,9 +80,9 @@ func (JobSpec) SwaggerDoc() map[string]string {
 
 var map_JobStatus = map[string]string{
 	"":               "JobStatus represents the current state of a Job.",
-	"conditions":     "The latest available observations of an object's current state. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
+	"conditions":     "The latest available observations of an object's current state. When a job fails, one of the conditions will have type == \"Failed\". More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
 	"startTime":      "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.",
-	"completionTime": "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.",
+	"completionTime": "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. The completion time is only set when the job finishes successfully.",
 	"active":         "The number of actively running pods.",
 	"succeeded":      "The number of pods which reached phase Succeeded.",
 	"failed":         "The number of pods which reached phase Failed.",