Wrap text for Pod Topology Spread Constraints

Wrapping helps localization teams pick up and work with changes.

Author: Tim Bannister

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md

@@ -7,7 +7,11 @@ weight: 40
 
 <!-- overview -->
 
-You can use _topology spread constraints_ to control how {{< glossary_tooltip text="Pods" term_id="Pod" >}} are spread across your cluster among failure-domains such as regions, zones, nodes, and other user-defined topology domains. This can help to achieve high availability as well as efficient resource utilization.
+You can use _topology spread constraints_ to control how
+{{< glossary_tooltip text="Pods" term_id="Pod" >}} are spread across your cluster
+among failure-domains such as regions, zones, nodes, and other user-defined topology
+domains. This can help to achieve high availability as well as efficient resource
+utilization.
 
 
 <!-- body -->
@@ -16,7 +20,9 @@ You can use _topology spread constraints_ to control how {{< glossary_tooltip te
 
 ### Node Labels
 
-Topology spread constraints rely on node labels to identify the topology domain(s) that each Node is in. For example, a Node might have labels: `node=node1,zone=us-east-1a,region=us-east-1`
+Topology spread constraints rely on node labels to identify the topology
+domain(s) that each Node is in. For example, a Node might have labels:
+`node=node1,zone=us-east-1a,region=us-east-1`
 
 Suppose you have a 4-node cluster with the following labels:
 
@@ -48,7 +54,9 @@ graph TB
     class zoneA,zoneB cluster;
 {{< /mermaid >}}
 
-Instead of manually applying labels, you can also reuse the [well-known labels](/docs/reference/labels-annotations-taints/) that are created and populated automatically on most clusters.
+Instead of manually applying labels, you can also reuse the
+[well-known labels](/docs/reference/labels-annotations-taints/) that are created and populated
+automatically on most clusters.
 
 ## Spread Constraints for Pods
 
@@ -70,7 +78,9 @@ spec:
       labelSelector: <object>
 ```
 
-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:
+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:
 
 - **maxSkew** describes the degree to which Pods may be unevenly distributed.
   It must be greater than zero. Its semantics differs according to the value of `whenUnsatisfiable`:
@@ -104,15 +114,24 @@ You can define one or multiple `topologySpreadConstraint` to instruct the kube-s
   in order to use it.
   {{< /note >}}
 
-- **topologyKey** is the key of node labels. If two Nodes are labelled with this key and have identical values for that label, the scheduler treats both Nodes as being in the same topology. The scheduler tries to place a balanced number of Pods into each topology domain.
+- **topologyKey** is the key of node labels. If two Nodes are labelled with this key
+  and have identical values for that label, the scheduler treats both Nodes as being
+  in the same topology. The scheduler tries to place a balanced number of Pods into
+  each topology domain.
 
 - **whenUnsatisfiable** indicates how to deal with a Pod if it doesn't satisfy the spread constraint:
   - `DoNotSchedule` (default) tells the scheduler not to schedule it.
   - `ScheduleAnyway` tells the scheduler to still schedule it while prioritizing nodes that minimize the skew.
 
-- **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.
+- **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.
 
-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.
+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`.
 
@@ -142,9 +161,14 @@ If we want an incoming Pod to be evenly spread with existing Pods across zones,
 
 {{< codenew file="pods/topology-spread-constraints/one-constraint.yaml" >}}
 
-`topologyKey: zone` implies the even distribution will only be applied to the nodes which have label pair "zone:&lt;any value&gt;" present. `whenUnsatisfiable: DoNotSchedule` tells the scheduler to let it stay pending if the incoming Pod can't satisfy the constraint.
+`topologyKey: zone` implies the even distribution will only be applied to the
+nodes which have label pair "zone:&lt;any value&gt;" present. `whenUnsatisfiable:
+DoNotSchedule` tells the scheduler to let it stay pending if the incoming Pod can't
+satisfy the constraint.
 
-If the scheduler placed this incoming Pod into "zoneA", the Pods distribution would become [3, 1], hence the actual skew is 2 (3 - 1) - which violates `maxSkew: 1`. In this example, the incoming Pod can only be placed into "zoneB":
+If the scheduler placed this incoming Pod into "zoneA", the Pods distribution would
+become [3, 1], hence the actual skew is 2 (3 - 1) - which violates `maxSkew: 1`. In
+this example, the incoming Pod can only be placed into "zoneB":
 
 {{<mermaid>}}
 graph BT
@@ -189,13 +213,21 @@ graph BT
 
 You can tweak the Pod spec to meet various kinds of requirements:
 
-- Change `maxSkew` to a bigger value like "2" so that the incoming Pod can be placed into "zoneA" as well.
-- Change `topologyKey` to "node" so as to distribute the Pods evenly across nodes instead of zones. In the above example, if `maxSkew` remains "1", the incoming Pod can only be placed onto "node4".
-- Change `whenUnsatisfiable: DoNotSchedule` to `whenUnsatisfiable: ScheduleAnyway` to ensure the incoming Pod to be always schedulable (suppose other scheduling APIs are satisfied). However, it's preferred to be placed onto the topology domain which has fewer matching Pods. (Be aware that this preferability is jointly normalized with other internal scheduling priorities like resource usage ratio, etc.)
+- Change `maxSkew` to a bigger value like "2" so that the incoming Pod can be placed
+  into "zoneA" as well.
+- Change `topologyKey` to "node" so as to distribute the Pods evenly across nodes
+  instead of zones. In the above example, if `maxSkew` remains "1", the incoming
+  Pod can only be placed onto "node4".
+- Change `whenUnsatisfiable: DoNotSchedule` to `whenUnsatisfiable: ScheduleAnyway`
+  to ensure the incoming Pod to be always schedulable (suppose other scheduling APIs
+  are satisfied). However, it's preferred to be placed into the topology domain which
+  has fewer matching Pods. (Be aware that this preferability is jointly normalized
+  with other internal scheduling priorities like resource usage ratio, etc.)
 
 ### Example: Multiple TopologySpreadConstraints
 
-This builds upon the previous example. Suppose you have a 4-node cluster where 3 Pods labeled `foo:bar` are located in node1, node2 and node3 respectively:
+This builds upon the previous example. Suppose you have a 4-node cluster where 3
+Pods labeled `foo:bar` are located in node1, node2 and node3 respectively:
 
 {{<mermaid>}}
 graph BT
@@ -220,7 +252,10 @@ You can use 2 TopologySpreadConstraints to control the Pods spreading on both zo
 
 {{< codenew file="pods/topology-spread-constraints/two-constraints.yaml" >}}
 
-In this case, to match the first constraint, the incoming Pod can only be placed into "zoneB"; while in terms of the second constraint, the incoming Pod can only be placed onto "node4". Then the results of 2 constraints are ANDed, so the only viable option is to place on "node4".
+In this case, to match the first constraint, the incoming Pod can only be placed into
+"zoneB"; while in terms of the second constraint, the incoming Pod can only be placed
+onto "node4". Then the results of 2 constraints are ANDed, so the only viable option
+is to place on "node4".
 
 Multiple constraints can lead to conflicts. Suppose you have a 3-node cluster across 2 zones:
 
@@ -243,13 +278,18 @@ graph BT
     class zoneA,zoneB cluster;
 {{< /mermaid >}}
 
-If you apply "two-constraints.yaml" to this cluster, you will notice "mypod" stays in `Pending` state. This is because: to satisfy the first constraint, "mypod" can only placed into "zoneB"; while in terms of the second constraint, "mypod" can only be placed onto "node2". Then a joint result of "zoneB" and "node2" returns nothing.
+If you apply "two-constraints.yaml" to this cluster, you will notice "mypod" stays in
+`Pending` state. This is because: to satisfy the first constraint, "mypod" can only placed
+into "zoneB"; while in terms of the second constraint, "mypod" can only be placed onto
+"node2". Then a joint result of "zoneB" and "node2" returns nothing.
 
-To overcome this situation, you can either increase the `maxSkew` or modify one of the constraints to use `whenUnsatisfiable: ScheduleAnyway`.
+To overcome this situation, you can either increase the `maxSkew` or modify one of
+the constraints to use `whenUnsatisfiable: ScheduleAnyway`.
 
 ### Interaction With Node Affinity and Node Selectors
 
-The scheduler will skip the non-matching nodes from the skew calculations if the incoming Pod has `spec.nodeSelector` or `spec.affinity.nodeAffinity` defined.
+The scheduler will skip the non-matching nodes from the skew calculations if the
+incoming Pod has `spec.nodeSelector` or `spec.affinity.nodeAffinity` defined.
 
 ### Example: TopologySpreadConstraints with NodeAffinity
 
@@ -287,11 +327,17 @@ class n5 k8s;
 class zoneC cluster;
 {{< /mermaid >}}
 
-and you know that "zoneC" must be excluded. In this case, you can compose the yaml as below, so that "mypod" will be placed into "zoneB" instead of "zoneC". Similarly `spec.nodeSelector` is also respected.
+and you know that "zoneC" must be excluded. In this case, you can compose the yaml
+as below, so that "mypod" will be placed into "zoneB" instead of "zoneC".
+Similarly `spec.nodeSelector` is also respected.
 
 {{< codenew file="pods/topology-spread-constraints/one-constraint-with-nodeaffinity.yaml" >}}
 
-The scheduler doesn't have prior knowledge of all the zones or other topology domains that a cluster has. They are determined from the existing nodes in the cluster. This could lead to a problem in autoscaled clusters, when a node pool (or node group) is scaled to zero nodes and the user is expecting them to scale up, because, in this case, those topology domains won't be considered until there is at least one node in them.
+The scheduler doesn't have prior knowledge of all the zones or other topology domains
+that a cluster has. They are determined from the existing nodes in the cluster. This
+could lead to a problem in autoscaled clusters, when a node pool (or node group) is
+scaled to zero nodes and the user is expecting them to scale up, because, in this case,
+those topology domains won't be considered until there is at least one node in them.
 
 ### Other Noticeable Semantics
 
@@ -301,10 +347,21 @@ There are some implicit conventions worth noting here:
 
 - The scheduler will bypass the nodes without `topologySpreadConstraints[*].topologyKey` present. This implies that:
 
-  1. the Pods located on those nodes do not impact `maxSkew` calculation - in the above example, suppose "node1" does not have label "zone", then the 2 Pods will be disregarded, hence the incoming Pod will be scheduled into "zoneA".
-  2. the incoming Pod has no chances to be scheduled onto such nodes - in the above example, suppose a "node5" carrying label `{zone-typo: zoneC}` joins the cluster, it will be bypassed due to the absence of label key "zone".
-
-- Be aware of what will happen if the incoming Pod's `topologySpreadConstraints[*].labelSelector` doesn't match its own labels. In the above example, if we remove the incoming Pod's labels, it can still be placed into "zoneB" since the constraints are still satisfied. However, after the placement, the degree of imbalance of the cluster remains unchanged - it's still zoneA having 2 Pods which hold label {foo:bar}, and zoneB having 1 Pod which holds label {foo:bar}. So if this is not what you expect, we recommend the workload's `topologySpreadConstraints[*].labelSelector` to match its own labels.
+  1. the Pods located on those nodes do not impact `maxSkew` calculation - in the
+     above example, suppose "node1" does not have label "zone", then the 2 Pods will
+     be disregarded, hence the incoming Pod will be scheduled into "zoneA".
+  2. the incoming Pod has no chances to be scheduled onto such nodes -
+     in the above example, suppose a "node5" carrying label `{zone-typo: zoneC}`
+     joins the cluster, it will be bypassed due to the absence of label key "zone".
+
+- Be aware of what will happen if the incomingPod's
+  `topologySpreadConstraints[*].labelSelector` doesn't match its own labels. In the
+  above example, if we remove the incoming Pod's labels, it can still be placed into
+  "zoneB" since the constraints are still satisfied. However, after the placement,
+  the degree of imbalance of the cluster remains unchanged - it's still zoneA
+  having 2 Pods which hold label {foo:bar}, and zoneB having 1 Pod which holds
+  label {foo:bar}. So if this is not what you expect, we recommend the workload's
+  `topologySpreadConstraints[*].labelSelector` to match its own labels.
 
 ### Cluster-level default constraints
 
@@ -405,15 +462,18 @@ scheduled - more packed or more scattered.
 For finer control, you can specify topology spread constraints to distribute
 Pods across different topology domains - to achieve either high availability or
 cost-saving. This can also help on rolling update workloads and scaling out
-replicas smoothly. See
+replicas smoothly.
+See
 [Motivation](https://github.com/kubernetes/enhancements/tree/master/keps/sig-scheduling/895-pod-topology-spread#motivation)
 for more details.
 
 ## Known Limitations
 
-- There's no guarantee that the constraints remain satisfied when Pods are removed. For example, scaling down a Deployment may result in imbalanced Pods distribution.
-You can use [Descheduler](https://github.com/kubernetes-sigs/descheduler) to rebalance the Pods distribution.
-- Pods matched on tainted nodes are respected. See [Issue 80921](https://github.com/kubernetes/kubernetes/issues/80921)
+- There's no guarantee that the constraints remain satisfied when Pods are removed. For
+  example, scaling down a Deployment may result in imbalanced Pods distribution.
+  You can use [Descheduler](https://github.com/kubernetes-sigs/descheduler) to rebalance the Pods distribution.
+- Pods matched on tainted nodes are respected.
+  See [Issue 80921](https://github.com/kubernetes/kubernetes/issues/80921).
 
 ## {{% heading "whatsnext" %}}