From def6c590adb8d0a880c028315172fd2ac0ceee41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filip=20K=C5=99epinsk=C3=BD?= <atiratree@gmail.com>
Date: Tue, 25 Mar 2025 14:45:51 +0100
Subject: [PATCH] Document .status.terminatingReplicas enabled by
 DeploymentPodReplacementPolicy feature

---
 .../concepts/workloads/controllers/deployment.md    | 13 +++++++++++++
 .../concepts/workloads/controllers/replicaset.md    | 13 +++++++++++++
 .../deployment-pod-replacement-policy.md            | 13 +++++++++++++
 3 files changed, 39 insertions(+)
 create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/deployment-pod-replacement-policy.md

diff --git a/content/en/docs/concepts/workloads/controllers/deployment.md b/content/en/docs/concepts/workloads/controllers/deployment.md
index 5dfe164055b20..44f12427a44ca 100644
--- a/content/en/docs/concepts/workloads/controllers/deployment.md
+++ b/content/en/docs/concepts/workloads/controllers/deployment.md
@@ -1327,6 +1327,19 @@ created Pod should be ready without any of its containers crashing, for it to be
 This defaults to 0 (the Pod will be considered available as soon as it is ready). To learn more about when
 a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
 
+### Terminating Pods
+
+{{< feature-state feature_gate_name="DeploymentPodReplacementPolicy" >}}
+
+You can enable this feature it by setting the `DeploymentPodReplacementPolicy`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+on the [API server](/docs/reference/command-line-tools-reference/kube-apiserver/)
+and on the [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume
+additional resources during that period. As a result, the total number of all pods can temporarily exceed
+`.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the Deployment.
+
 ### Revision History Limit
 
 A Deployment's revision history is stored in the ReplicaSets it controls.
diff --git a/content/en/docs/concepts/workloads/controllers/replicaset.md b/content/en/docs/concepts/workloads/controllers/replicaset.md
index 5f27e1d48b74f..926ff0359b4c4 100644
--- a/content/en/docs/concepts/workloads/controllers/replicaset.md
+++ b/content/en/docs/concepts/workloads/controllers/replicaset.md
@@ -320,6 +320,19 @@ To update Pods to a new spec in a controlled way, use a
 [Deployment](/docs/concepts/workloads/controllers/deployment/#creating-a-deployment), as
 ReplicaSets do not support a rolling update directly.
 
+### Terminating Pods
+
+{{< feature-state feature_gate_name="DeploymentPodReplacementPolicy" >}}
+
+You can enable this feature it by setting the `DeploymentPodReplacementPolicy`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+on the [API server](/docs/reference/command-line-tools-reference/kube-apiserver/)
+and on the [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume
+additional resources during that period. As a result, the total number of all pods can temporarily exceed
+`.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the ReplicaSet.
+
 ### Isolating Pods from a ReplicaSet
 
 You can remove Pods from a ReplicaSet by changing their labels. This technique may be used to remove Pods
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/deployment-pod-replacement-policy.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/deployment-pod-replacement-policy.md
new file mode 100644
index 0000000000000..5c5c562a92783
--- /dev/null
+++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/deployment-pod-replacement-policy.md
@@ -0,0 +1,13 @@
+---
+title: DeploymentPodReplacementPolicy
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.33"
+---
+Enables a new status field `.status.terminatingReplicas` in Deployments and ReplicaSets to allow tracking of terminating pods.