Graduate JobTrackingWithFinalizers to stable (#37764)

* Graduate JobTrackingWithFinalizers to stable

* JobTrackingWithFinalizers disabled in 1.23, 1.24

content/en/docs/concepts/workloads/controllers/job.md

@@ -1,5 +1,6 @@
 ---
 reviewers:
+- alculquicondor
 - erictune
 - soltysh
 title: Jobs
@@ -313,10 +314,6 @@ The number of retries is calculated in two ways:
 If either of the calculations reaches the `.spec.backoffLimit`, the Job is
 considered failed.
 
-When the [`JobTrackingWithFinalizers`](#job-tracking-with-finalizers) feature is
-disabled, the number of failed Pods is only based on Pods that are still present
-in the API.
-
 {{< note >}}
 If your job has `restartPolicy = "OnFailure"`, keep in mind that your Pod running the Job
 will be terminated once the job backoff limit has been reached. This can make debugging the Job's executable more difficult. We suggest setting
@@ -780,43 +777,33 @@ These are some requirements and semantics of the API:
 
 ### Job tracking with finalizers
 
-{{< feature-state for_k8s_version="v1.23" state="beta" >}}
+{{< feature-state for_k8s_version="v1.26" state="stable" >}}
 
 {{< note >}}
-In order to use this behavior, you must enable the `JobTrackingWithFinalizers`
-[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
-on the [API server](/docs/reference/command-line-tools-reference/kube-apiserver/)
-and the [controller manager](/docs/reference/command-line-tools-reference/kube-controller-manager/).
-
-When enabled, the control plane tracks new Jobs using the behavior described
-below. Jobs created before the feature was enabled are unaffected. As a user,
-the only difference you would see is that the control plane tracking of Job
-completion is more accurate.
+The control plane doesn't track Jobs using finalizers, if the Jobs were created
+when the feature gate `JobTrackingWithFinalizers` was disabled, even after you
+upgrade the control plane to 1.26.
 {{< /note >}}
 
-When this feature isn't enabled, the Job {{< glossary_tooltip term_id="controller" >}}
-relies on counting the Pods that exist in the cluster to track the Job status,
-that is, to keep the counters for `succeeded` and `failed` Pods.
-However, Pods can be removed for a number of reasons, including:
-- The garbage collector that removes orphan Pods when a Node goes down.
-- The garbage collector that removes finished Pods (in `Succeeded` or `Failed`
-  phase) after a threshold.
-- Human intervention to delete Pods belonging to a Job.
-- An external controller (not provided as part of Kubernetes) that removes or
-  replaces Pods.
-
-If you enable the `JobTrackingWithFinalizers` feature for your cluster, the
-control plane keeps track of the Pods that belong to any Job and notices if any
-such Pod is removed from the API server. To do that, the Job controller creates Pods with
-the finalizer `batch.kubernetes.io/job-tracking`. The controller removes the
-finalizer only after the Pod has been accounted for in the Job status, allowing
-the Pod to be removed by other controllers or users.
-
-The Job controller uses the new algorithm for new Jobs only. Jobs created
-before the feature is enabled are unaffected. You can determine if the Job
-controller is tracking a Job using Pod finalizers by checking if the Job has the
-annotation `batch.kubernetes.io/job-tracking`. You should **not** manually add
-or remove this annotation from Jobs.
+The control plane keeps track of the Pods that belong to any Job and notices if
+any such Pod is removed from the API server. To do that, the Job controller
+creates Pods with the finalizer `batch.kubernetes.io/job-tracking`. The
+controller removes the finalizer only after the Pod has been accounted for in
+the Job status, allowing the Pod to be removed by other controllers or users.
+
+Jobs created before upgrading to Kubernetes 1.26 or before the feature gate
+`JobTrackingWithFinalizers` is enabled are tracked without the use of Pod
+finalizers.
+The Job {{< glossary_tooltip term_id="controller" text="controller" >}} updates
+the status counters for `succeeded` and `failed` Pods based only on the Pods
+that exist in the cluster. The contol plane can lose track of the progress of
+the Job if Pods are deleted from the cluster.
+
+You can determine if the control plane is tracking a Job using Pod finalizers by
+checking if the Job has the annotation
+`batch.kubernetes.io/job-tracking`. You should **not** manually add or remove
+this annotation from Jobs. Instead, you can recreate the Jobs to ensure they
+are tracked using Pod finalizers.
 
 ## Alternatives
 

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -115,8 +115,6 @@ For a reference to old feature gates that are removed, please refer to
 | `JobPodFailurePolicy` | `false` | Alpha | 1.25 | - |
 | `JobReadyPods` | `false` | Alpha | 1.23 | 1.23 |
 | `JobReadyPods` | `true` | Beta | 1.24 | |
-| `JobTrackingWithFinalizers` | `false` | Alpha | 1.22 | 1.22 |
-| `JobTrackingWithFinalizers` | `true` | Beta | 1.23 | |
 | `KubeletCredentialProviders` | `false` | Alpha | 1.20 | 1.23 |
 | `KubeletCredentialProviders` | `true` | Beta | 1.24 | |
 | `KubeletInUserNamespace` | `false` | Alpha | 1.22 | |
@@ -283,6 +281,10 @@ For a reference to old feature gates that are removed, please refer to
 | `IndexedJob` | `false` | Alpha | 1.21 | 1.21 |
 | `IndexedJob` | `true` | Beta | 1.22 | 1.23 |
 | `IndexedJob` | `true` | GA | 1.24 | - |
+| `JobTrackingWithFinalizers` | `false` | Alpha | 1.22 | 1.22 |
+| `JobTrackingWithFinalizers` | `false` | Beta | 1.23 | 1.24 |
+| `JobTrackingWithFinalizers` | `true` | Beta | 1.25 | 1.25 |
+| `JobTrackingWithFinalizers` | `true` | GA | 1.26 | - |
 | `LocalStorageCapacityIsolation` | `false` | Alpha | 1.7 | 1.9 |
 | `LocalStorageCapacityIsolation` | `true` | Beta | 1.10 | 1.24 |
 | `LocalStorageCapacityIsolation` | `true` | GA | 1.25 | - |

content/en/docs/reference/labels-annotations-taints/_index.md

@@ -513,15 +513,23 @@ The {{< glossary_tooltip text="control plane" term_id="control-plane" >}} adds t
 
 If the number of backend endpoints falls below 1000, the control plane removes this annotation.
 
-### batch.kubernetes.io/job-tracking
+### batch.kubernetes.io/job-tracking (deprecated) {#batch-kubernetes-io-job-tracking}
 
 Example: `batch.kubernetes.io/job-tracking: ""`
 
 Used on: Jobs
 
 The presence of this annotation on a Job indicates that the control plane is
 [tracking the Job status using finalizers](/docs/concepts/workloads/controllers/job/#job-tracking-with-finalizers).
-You should **not** manually add or remove this annotation.
+The control plane uses this annotation to safely transition to tracking Jobs
+using finalizers, while the feature is in development.
+You should **not** manually add or remove this annotation. 
+
+{{< note >}}
+Starting from Kubernetes 1.26, this annotation is deprecated.
+Kubernetes 1.27 and newer will ignore this annotation and always track Jobs
+using finalizers.
+{{< /note >}}
 
 ### scheduler.alpha.kubernetes.io/defaultTolerations {#scheduleralphakubernetesio-defaulttolerations}