Document the new NodeInclusionPolicyInPodTopologySpread feature gate

Signed-off-by: kerthcet <[email protected]>

Author: kerthcet

content/en/docs/concepts/workloads/pods/pod-topology-spread-constraints.md

@@ -68,6 +68,8 @@ spec:
       topologyKey: <string>
       whenUnsatisfiable: <string>
       labelSelector: <object>
+      nodeAffinityPolicy: <string> # optional; alpha since v1.25
+      nodeTaintsPolicy: <string> # optional; alpha since v1.25
 ```
 
 You can define one or multiple `topologySpreadConstraint` to instruct the kube-scheduler how to place each incoming Pod in relation to the existing Pods across your cluster. The fields are:
@@ -93,7 +95,7 @@ You can define one or multiple `topologySpreadConstraint` to instruct the kube-s
     Pod topology spread treats "global minimum" as 0, and then the calculation of `skew` is performed.
     The "global minimum" is the minimum number of matching Pods in an eligible domain,
     or zero if the number of eligible domains is less than `minDomains`.
-  - When the number of eligible domains with matching topology keys equals or is greater than 
+  - When the number of eligible domains with matching topology keys equals or is greater than
     `minDomains`, this value has no effect on scheduling.
   - When `minDomains` is nil, the constraint behaves as if `minDomains` is 1.
   - When `minDomains` is not nil, the value of `whenUnsatisfiable` must be "`DoNotSchedule`".
@@ -112,6 +114,33 @@ You can define one or multiple `topologySpreadConstraint` to instruct the kube-s
 
 - **labelSelector** is used to find matching Pods. Pods that match this label selector are counted to determine the number of Pods in their corresponding topology domain. See [Label Selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors) for more details.
 
+- **nodeAffinityPolicy** indicates how we will treat Pod's nodeAffinity/nodeSelector
+when calculating pod topology spread skew. Options are:
+  - Honor: only nodes matching nodeAffinity/nodeSelector are included in the calculations.
+  - Ignore: nodeAffinity/nodeSelector are ignored. All nodes are included in the calculations.
+
+  If this value is nil, the behavior is equivalent to the Honor policy.
+
+  {{< note >}}
+  The `nodeAffinityPolicy` is an alpha-level field added in 1.25. You have to enable the
+  `NodeInclusionPolicyInPodTopologySpread` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+  in order to use it.
+  {{< /note >}}
+
+- **nodeTaintsPolicy** indicates how we will treat node taints when calculating
+pod topology spread skew. Options are:
+  - Honor: nodes without taints, along with tainted nodes for which the incoming pod
+	  has a toleration, are included.
+  - Ignore: node taints are ignored. All nodes are included.
+
+  If this value is nil, the behavior is equivalent to the Ignore policy.
+
+  {{< note >}}
+  The `nodeTaintsPolicy` is an alpha-level field added in 1.25. You have to enable the
+  `NodeInclusionPolicyInPodTopologySpread` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+  in order to use it.
+  {{< /note >}}
+
 When a Pod defines more than one `topologySpreadConstraint`, those constraints are ANDed: The kube-scheduler looks for a node for the incoming Pod that satisfies all the constraints.
 
 You can read more about this field by running `kubectl explain Pod.spec.topologySpreadConstraints`.

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

@@ -156,6 +156,7 @@ different Kubernetes components.
 | `NetworkPolicyEndPort` | `false` | Alpha | 1.21 | 1.21 |
 | `NetworkPolicyEndPort` | `true` | Beta | 1.22 |  |
 | `NetworkPolicyStatus` | `false` | Alpha | 1.24 |  |
+| `NodeInclusionPolicyInPodTopologySpread` | `false` | Alpha | 1.25 |
 | `NodeSwap` | `false` | Alpha | 1.22 | |
 | `NodeOutOfServiceVolumeDetach` | `false` | Alpha | 1.24 | |
 | `OpenAPIEnums` | `false` | Alpha | 1.23 | 1.23 |
@@ -1007,6 +1008,9 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `NetworkPolicyEndPort`: Enable use of the field `endPort` in NetworkPolicy objects,
   allowing the selection of a port range instead of a single port.
 - `NetworkPolicyStatus`: Enable the `status` subresource for NetworkPolicy objects.
+- `NodeInclusionPolicyInPodTopologySpread`: Enable using `nodeAffinityPolicy` and `nodeTaintsPolicy`
+  in Pod [topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/)
+  when calculating pod topology spread skew.
 - `NodeDisruptionExclusion`: Enable use of the Node label `node.kubernetes.io/exclude-disruption`
   which prevents nodes from being evacuated during zone failures.
 - `NodeLease`: Enable the new Lease API to report node heartbeats, which could be used as a node health signal.