Merge pull request #78674 from abrennan89/OSDOCS-4526

OSDOCS-4526: Improvement of the docs about Pod Topology Spread Contraints under Nodes

Author: abrennan89

modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc

@@ -2,18 +2,53 @@
 //
 // * nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints
 
+:_mod-docs-content-type: REFERENCE
 [id="nodes-scheduler-pod-topology-spread-constraints-examples_{context}"]
-= Example pod topology spread constraints
+= Example configurations for pod topology spread constraints
 
-The following examples demonstrate pod topology spread constraint configurations.
-
-[id="nodes-scheduler-pod-topology-spread-constraints-example-single_{context}"]
-== Single pod topology spread constraint example
+You can specify which pods to group together, which topology domains they are spread among, and the acceptable skew.
 
-// TODO: Add a diagram?
+The following examples demonstrate pod topology spread constraint configurations.
 
-This example `Pod` spec defines one pod topology spread constraint. It matches on pods labeled `region: us-east`, distributes among zones, specifies a skew of `1`, and does not schedule the pod if it does not meet these requirements.
+.Example to distribute pods that match the specified labels based on their zone
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: my-pod
+  labels:
+    region: us-east
+spec:
+  securityContext:
+    runAsNonRoot: true
+    seccompProfile:
+      type: RuntimeDefault
+  topologySpreadConstraints:
+  - maxSkew: 1 <1>
+    topologyKey: topology.kubernetes.io/zone <2>
+    whenUnsatisfiable: DoNotSchedule <3>
+    labelSelector: <4>
+      matchLabels:
+        region: us-east <5>
+    matchLabelKeys:
+      - my-pod-label <6>
+  containers:
+  - image: "docker.io/ocpqe/hello-pod"
+    name: hello-pod
+    securityContext:
+      allowPrivilegeEscalation: false
+      capabilities:
+        drop: [ALL]
+----
+<1> The maximum difference in number of pods between any two topology domains. The default is `1`, and you cannot specify a value of `0`.
+<2> The key of a node label. Nodes with this key and identical value are considered to be in the same topology.
+<3> How to handle a pod if it does not satisfy the spread constraint. The default is `DoNotSchedule`, which tells the scheduler not to schedule the pod. Set to `ScheduleAnyway` to still schedule the pod, but the scheduler prioritizes honoring the skew to not make the cluster more imbalanced.
+<4> Pods that match this label selector are counted and recognized as a group when spreading to satisfy the constraint. Be sure to specify a label selector, otherwise no pods can be matched.
+<5> Be sure that this `Pod` spec also sets its labels to match this label selector if you want it to be counted properly in the future.
+<6> A list of pod label keys to select which pods to calculate spreading over.
 
+.Example demonstrating a single pod topology spread constraint
 [source,yaml]
 ----
 kind: Pod
@@ -43,15 +78,9 @@ spec:
         drop: [ALL]
 ----
 
-[id="nodes-scheduler-pod-topology-spread-constraints-example-multiple_{context}"]
-== Multiple pod topology spread constraints example
-
-// TODO: Add a diagram?
-
-This example `Pod` spec defines two pod topology spread constraints. Both match on pods labeled `region: us-east`, specify a skew of `1`, and do not schedule the pod if it does not meet these requirements.
-
-The first constraint distributes pods based on a user-defined label `node`, and the second constraint distributes pods based on a user-defined label `rack`. Both constraints must be met for the pod to be scheduled.
+The previous example defines a `Pod` spec with a one pod topology spread constraint. It matches on pods labeled `region: us-east`, distributes among zones, specifies a skew of `1`, and does not schedule the pod if it does not meet these requirements.
 
+.Example demonstrating multiple pod topology spread constraints
 [source,yaml]
 ----
 kind: Pod
@@ -86,3 +115,7 @@ spec:
       capabilities:
         drop: [ALL]
 ----
+
+The previous example defines a `Pod` spec with two pod topology spread constraints. Both match on pods labeled `region: us-east`, specify a skew of `1`, and do not schedule the pod if it does not meet these requirements.
+
+The first constraint distributes pods based on a user-defined label `node`, and the second constraint distributes pods based on a user-defined label `rack`. Both constraints must be met for the pod to be scheduled.

modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints
+
+:_mod-docs-content-type: CONCEPT
+[id="pod-topology-spread-constraints-max-skew_{context}"]
+= Understanding skew and maxSkew
+
+Skew refers to the difference in the number of pods that match a specified label selector across different topology domains, such as zones or nodes.
+
+The skew is calculated for each domain by taking the absolute difference between the number of pods in that domain and the number of pods in the domain with the lowest amount of pods scheduled. Setting a `maxSkew` value guides the scheduler to maintain a balanced pod distribution.
+
+[id="pod-topology-spread-constraints-max-skew-calculation_{context}"]
+== Example skew calculation
+
+You have three zones (A, B, and C), and you want to distribute your pods evenly across these zones. If zone A has 5 pods, zone B has 3 pods, and zone C has 2 pods, to find the skew, you can subtract the number of pods in the domain with the lowest amount of pods scheduled from the number of pods currently in each zone. This means that the skew for zone A is 3, the skew for zone B is 1, and the skew for zone C is 0.
+
+[id="pod-topology-spread-constraints-max-skew-parameter_{context}"]
+== The maxSkew parameter
+
+The `maxSkew` parameter defines the maximum allowable difference, or skew, in the number of pods between any two topology domains. If `maxSkew` is set to `1`, the number of pods in any topology domain should not differ by more than 1 from any other domain. If the skew exceeds `maxSkew`, the scheduler attempts to place new pods in a way that reduces the skew, adhering to the constraints.
+
+Using the previous example skew calculation, the skew values exceed the default `maxSkew` value of `1`. The scheduler places new pods in zone B and zone C to reduce the skew and achieve a more balanced distribution, ensuring that no topology domain exceeds the skew of 1.

modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc

@@ -6,15 +6,29 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can use pod topology spread constraints to control the placement of your pods across nodes, zones, regions, or other user-defined topology domains.
+You can use pod topology spread constraints to provide fine-grained control over the placement of your pods across nodes, zones, regions, or other user-defined topology domains. Distributing pods across failure domains can help to achieve high availability and more efficient resource utilization.
 
-// About pod topology spread constraints
-include::modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc[leveloffset=+1]
+[id="nodes-scheduler-pod-topology-spread-constraints-example-use-cases"]
+== Example use cases
 
-// Configuring pod topology spread constraints
-include::modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc[leveloffset=+1]
+* As an administrator, I want my workload to automatically scale between two to fifteen pods. I want to ensure that when there are only two pods, they are not placed on the same node, to avoid a single point of failure.
 
-// Sample pod topology spread constraints
+* As an administrator, I want to distribute my pods evenly across multiple infrastructure zones to reduce latency and network costs. I want to ensure that my cluster can self-heal if issues arise.
+
+[id="nodes-scheduler-pod-topology-spread-constraints-considerations"]
+== Important considerations
+
+* Pods in an {product-title} cluster are managed by _workload controllers_ such as deployments, stateful sets, or daemon sets. These controllers define the desired state for a group of pods, including how they are distributed and scaled across the nodes in the cluster. You should set the same pod topology spread constraints on all pods in a group to avoid confusion. When using a workload controller, such as a deployment, the pod template typically handles this for you.
+
+* Mixing different pod topology spread constraints can make {product-title} behavior confusing and troubleshooting more difficult. You can avoid this by ensuring that all nodes in a topology domain are consistently labeled. {product-title} automatically populates well-known labels, such as `kubernetes.io/hostname`. This helps avoid the need for manual labeling of nodes. These labels provide essential topology information, ensuring consistent node labeling across the cluster.
+
+* Only pods within the same namespace are matched and grouped together when spreading due to a constraint.
+
+* You can specify multiple pod topology spread constraints, but you must ensure that they do not conflict with each other. All pod topology spread constraints must be satisfied for a pod to be placed.
+
+include::modules/pod-topology-spread-constraints-max-skew.adoc[leveloffset=+1]
+
+// Example pod topology spread constraints
 include::modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc[leveloffset=+1]
 
 ifndef::openshift-rosa,openshift-dedicated[]