Merge pull request #98817 from alculquicondor/job-completion-api

Add Job.status.uncountedTerminatedPods for Job tracking

Kubernetes-commit: b76549665070beb2cc1a0410a6c7f66d8007f76b

batch/v1/types.go

@@ -19,9 +19,20 @@ package v1
 import (
 	"k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
 )
 
-const JobCompletionIndexAnnotation = "batch.kubernetes.io/job-completion-index"
+const (
+	JobCompletionIndexAnnotation = "batch.kubernetes.io/job-completion-index"
+
+	// JobTrackingFinalizer is a finalizer for Job's pods. It prevents them from
+	// being deleted before being accounted in the Job status.
+	// The apiserver and job controller use this string as a Job annotation, to
+	// mark Jobs that are being tracked using pod finalizers. Two releases after
+	// the JobTrackingWithFinalizers graduates to GA, JobTrackingFinalizer will
+	// no longer be used as a Job annotation.
+	JobTrackingFinalizer = "batch.kubernetes.io/job-tracking"
+)
 
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -237,6 +248,38 @@ type JobStatus struct {
 	// represented as "1,3-5,7".
 	// +optional
 	CompletedIndexes string `json:"completedIndexes,omitempty" protobuf:"bytes,7,opt,name=completedIndexes"`
+
+	// UncountedTerminatedPods holds the UIDs of Pods that have terminated but
+	// the job controller hasn't yet accounted for in the status counters.
+	//
+	// The job controller creates pods with a finalizer. When a pod terminates
+	// (succeeded or failed), the controller does three steps to account for it
+	// in the job status:
+	// (1) Add the pod UID to the arrays in this field.
+	// (2) Remove the pod finalizer.
+	// (3) Remove the pod UID from the arrays while increasing the corresponding
+	//     counter.
+	//
+	// This field is alpha-level. The job controller only makes use of this field
+	// when the feature gate PodTrackingWithFinalizers is enabled.
+	// Old jobs might not be tracked using this field, in which case the field
+	// remains null.
+	// +optional
+	UncountedTerminatedPods *UncountedTerminatedPods `json:"uncountedTerminatedPods,omitempty" protobuf:"bytes,8,opt,name=uncountedTerminatedPods"`
+}
+
+// UncountedTerminatedPods holds UIDs of Pods that have terminated but haven't
+// been accounted in Job status counters.
+type UncountedTerminatedPods struct {
+	// Succeeded holds UIDs of succeeded Pods.
+	// +listType=set
+	// +optional
+	Succeeded []types.UID `json:"succeeded,omitempty" protobuf:"bytes,1,rep,name=succeeded,casttype=k8s.io/apimachinery/pkg/types.UID"`
+
+	// Failed holds UIDs of failed Pods.
+	// +listType=set
+	// +optional
+	Failed []types.UID `json:"failed,omitempty" protobuf:"bytes,2,rep,name=failed,casttype=k8s.io/apimachinery/pkg/types.UID"`
 }
 
 type JobConditionType string

batch/v1/types_swagger_doc_generated.go

@@ -128,14 +128,15 @@ 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. When a Job fails, one of the conditions will have type \"Failed\" and status true. When a Job is suspended, one of the conditions will have type \"Suspended\" and status true; when the Job is resumed, the status of this condition will become false. When a Job is completed, one of the conditions will have type \"Complete\" and status true. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
-	"startTime":        "Represents time when the job controller started processing a job. When a Job is created in the suspended state, this field is not set until the first time it is resumed. This field is reset every time a Job is resumed from suspension. 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.",
-	"completedIndexes": "CompletedIndexes holds the completed indexes when .spec.completionMode = \"Indexed\" in a text format. The indexes are represented as decimal integers separated by commas. The numbers are listed in increasing order. Three or more consecutive numbers are compressed and represented by the first and last element of the series, separated by a hyphen. For example, if the completed indexes are 1, 3, 4, 5 and 7, they are represented as \"1,3-5,7\".",
+	"":                        "JobStatus represents the current state of a Job.",
+	"conditions":              "The latest available observations of an object's current state. When a Job fails, one of the conditions will have type \"Failed\" and status true. When a Job is suspended, one of the conditions will have type \"Suspended\" and status true; when the Job is resumed, the status of this condition will become false. When a Job is completed, one of the conditions will have type \"Complete\" and status true. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/",
+	"startTime":               "Represents time when the job controller started processing a job. When a Job is created in the suspended state, this field is not set until the first time it is resumed. This field is reset every time a Job is resumed from suspension. 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.",
+	"completedIndexes":        "CompletedIndexes holds the completed indexes when .spec.completionMode = \"Indexed\" in a text format. The indexes are represented as decimal integers separated by commas. The numbers are listed in increasing order. Three or more consecutive numbers are compressed and represented by the first and last element of the series, separated by a hyphen. For example, if the completed indexes are 1, 3, 4, 5 and 7, they are represented as \"1,3-5,7\".",
+	"uncountedTerminatedPods": "UncountedTerminatedPods holds the UIDs of Pods that have terminated but the job controller hasn't yet accounted for in the status counters.\n\nThe job controller creates pods with a finalizer. When a pod terminates (succeeded or failed), the controller does three steps to account for it in the job status: (1) Add the pod UID to the arrays in this field. (2) Remove the pod finalizer. (3) Remove the pod UID from the arrays while increasing the corresponding\n    counter.\n\nThis field is alpha-level. The job controller only makes use of this field when the feature gate PodTrackingWithFinalizers is enabled. Old jobs might not be tracked using this field, in which case the field remains null.",
 }
 
 func (JobStatus) SwaggerDoc() map[string]string {
@@ -152,4 +153,14 @@ func (JobTemplateSpec) SwaggerDoc() map[string]string {
 	return map_JobTemplateSpec
 }
 
+var map_UncountedTerminatedPods = map[string]string{
+	"":          "UncountedTerminatedPods holds UIDs of Pods that have terminated but haven't been accounted in Job status counters.",
+	"succeeded": "Succeeded holds UIDs of succeeded Pods.",
+	"failed":    "Failed holds UIDs of failed Pods.",
+}
+
+func (UncountedTerminatedPods) SwaggerDoc() map[string]string {
+	return map_UncountedTerminatedPods
+}
+
 // AUTO-GENERATED FUNCTIONS END HERE

go.mod

@@ -7,7 +7,7 @@ go 1.16
 require (
 	github.com/gogo/protobuf v1.3.2
 	github.com/stretchr/testify v1.7.0
-	k8s.io/apimachinery v0.0.0-20210708014216-0dafcb48b31e
+	k8s.io/apimachinery v0.0.0-20210708214246-ff522ab81c74
 )
 
-replace k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20210708014216-0dafcb48b31e
+replace k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20210708214246-ff522ab81c74

go.sum

@@ -207,8 +207,8 @@ gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v
 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
-k8s.io/apimachinery v0.0.0-20210708014216-0dafcb48b31e h1:EZ+ZrcPtnkR8vVo7bBSwoMD9a0HaC29O6lJhcZgwsJQ=
-k8s.io/apimachinery v0.0.0-20210708014216-0dafcb48b31e/go.mod h1:O3oNtNadZdeOMxHFVxOreoznohCpy0z6mocxbZr7oJ0=
+k8s.io/apimachinery v0.0.0-20210708214246-ff522ab81c74 h1:Daxg4VCqUpkKuMJjia7XcVVDHnPjH6IeKb7jcZDcQUM=
+k8s.io/apimachinery v0.0.0-20210708214246-ff522ab81c74/go.mod h1:O3oNtNadZdeOMxHFVxOreoznohCpy0z6mocxbZr7oJ0=
 k8s.io/gengo v0.0.0-20200413195148-3a45101e95ac/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0=
 k8s.io/klog/v2 v2.0.0/go.mod h1:PBfzABfn139FHAV07az/IF9Wp1bkk3vpT2XSJ76fSDE=
 k8s.io/klog/v2 v2.9.0 h1:D7HV+n1V57XeZ0m6tdRkfknthUaM06VFbWldOFh8kzM=

testdata/HEAD/batch.v1.Job.json

@@ -1565,6 +1565,14 @@
     "active": 543081713,
     "succeeded": -377965530,
     "failed": 77405208,
-    "completedIndexes": "495"
+    "completedIndexes": "495",
+    "uncountedTerminatedPods": {
+      "succeeded": [
+        "Ʊ巭銔07?为Èá網抒h"
+      ],
+      "failed": [
+        "W"
+      ]
+    }
   }
 }

testdata/HEAD/batch.v1.Job.yaml

@@ -1072,3 +1072,8 @@ status:
     type: ɓ为\Ŧƺ猑\#ȼ縤ɰTaI楅©
   failed: 77405208
   succeeded: -377965530
+  uncountedTerminatedPods:
+    failed:
+    - W
+    succeeded:
+    - Ʊ巭銔07?为Èá網抒h