OSDOCS NODES 7: Scheduling Configuration (Scheduler, Affinity) I

modules/nodes-scheduler-node-affinity-about.adoc

@@ -6,9 +6,8 @@
 [id="nodes-scheduler-node-affinity-about_{context}"]
 = Understanding node affinity
 
-Node affinity allows a pod to specify an affinity towards a group of nodes it can be placed on. The node does not have control over the placement.
-
-For example, you could configure a pod to only run on a node with a specific CPU or in a specific availability zone.
+[role="_abstract"]
+To specify a preference towards a group of nodes that a pod can be placed on, you can use a node affinity in the pod spec. For example, you could configure a pod to run only on a node with a specific CPU or in a specific availability zone. The node does not have control over the placement.
 
 There are two types of node affinity rules: _required_ and _preferred_.
 
@@ -36,15 +35,15 @@ spec:
     seccompProfile:
       type: RuntimeDefault
   affinity:
-    nodeAffinity: <1>
-      requiredDuringSchedulingIgnoredDuringExecution: <2>
+    nodeAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
         nodeSelectorTerms:
         - matchExpressions:
-          - key: e2e-az-NorthSouth <3>
-            operator: In <4>
+          - key: e2e-az-NorthSouth
+            operator: In
             values:
-            - e2e-az-North <3>
-            - e2e-az-South <3>
+            - e2e-az-North
+            - e2e-az-South
   containers:
   - name: with-node-affinity
     image: docker.io/ocpqe/hello-pod
@@ -54,11 +53,16 @@ spec:
         drop: [ALL]
 # ...
 ----
+where:
 
-<1> The stanza to configure node affinity.
-<2> Defines a required rule.
-<3> The key/value pair (label) that must be matched to apply the rule.
-<4> The operator represents the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`.
+`spec.affinity.nodeAffinity`:: Specifies the stanza to configure node affinity.
+`spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution`:: Specifies a _required_ rule. Configure the following `nodeSelectorTerms.matchExpressions` parameters:
++
+--
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+--
 
 The following example is a node specification with a preferred rule that a node with a label whose key is `e2e-az-EastWest` and whose value is either `e2e-az-East` or `e2e-az-West` is preferred for the pod:
 
@@ -75,16 +79,16 @@ spec:
     seccompProfile:
       type: RuntimeDefault
   affinity:
-    nodeAffinity: <1>
-      preferredDuringSchedulingIgnoredDuringExecution: <2>
-      - weight: 1 <3>
+    nodeAffinity:
+      preferredDuringSchedulingIgnoredDuringExecution:
+      - weight: 1
         preference:
           matchExpressions:
-          - key: e2e-az-EastWest <4>
-            operator: In <5>
+          - key: e2e-az-EastWest
+            operator: In
             values:
-            - e2e-az-East <4>
-            - e2e-az-West <4>
+            - e2e-az-East
+            - e2e-az-West
   containers:
   - name: with-node-affinity
     image: docker.io/ocpqe/hello-pod
@@ -94,16 +98,17 @@ spec:
         drop: [ALL]
 # ...
 ----
-
-<1> The stanza to configure node affinity.
-<2> Defines a preferred rule.
-<3> Specifies a weight for a preferred rule. The node with highest weight is preferred.
-<4> The key/value pair (label) that must be matched to apply the rule.
-<5> The operator represents the relationship between the label on the node and
-the set of values in the `matchExpression` parameters in the `Pod` spec.
-This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`.
-
-There is no explicit _node anti-affinity_ concept, but using the `NotIn` or `DoesNotExist` operator replicates that behavior.
+where:
+
+`spec.affinity.nodeAffinity`:: Specifies the stanza to configure node affinity.
+`spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution`:: Specifies a _preferred_ rule. Configure a weight and the following `preference.matchExpression` parameters:
++
+--
+`weight`:: Specifies a weight for a preferred rule. The node with highest weight is preferred.
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`. There is no explicit _node anti-affinity_ concept, but using the `NotIn` or `DoesNotExist` operator replicates that behavior.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+--
 
 [NOTE]
 ====

modules/nodes-scheduler-node-affinity-configuring-preferred.adoc

@@ -6,11 +6,14 @@
 [id="nodes-scheduler-node-affinity-configuring-preferred_{context}"]
 = Configuring a preferred node affinity rule
 
-Preferred rules specify that, if the rule is met, the scheduler tries to enforce the rules, but does not guarantee enforcement.
+[role="_abstract"]
+You can use a _preferred_ rule to instruct the scheduler that if a matching node is not available, schedule the pod on a different node to ensure the workload application runs.
 
-.Procedure
+For a preferred rule, the scheduler tries to enforce the rule, but does not guarantee enforcement. 
+
+The following procedure demonstrates a simple configuration that creates a node and a pod that the scheduler tries to place on the node.
 
-The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler tries to place on the node.
+.Procedure
 
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 . Add a label to a node using the `oc label node` command:
@@ -37,23 +40,29 @@ kind: Pod
 metadata:
   name: s1
 spec:
-  affinity: <1>
+  affinity:
     nodeAffinity:
-      preferredDuringSchedulingIgnoredDuringExecution: <2>
-      - weight: <3>
+      preferredDuringSchedulingIgnoredDuringExecution:
+      - weight:
         preference:
           matchExpressions:
-          - key: e2e-az-name <4>
+          - key: e2e-az-name
             values:
             - e2e-az3
-            operator: In <5>
+            operator: In
 #...
 ----
-<1> Adds a pod affinity.
-<2> Configures the `preferredDuringSchedulingIgnoredDuringExecution` parameter.
-<3> Specifies a weight for the node, as a number 1-100. The node with highest weight is preferred.
-<4> Specifies the `key` and `values` that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `values` parameters as the label in the node.
-<5> Specifies an `operator`. The operator can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. For example, use the operator `In` to require the label to be in the node.
+where:
+
+`spec.affinity.nodeAffinity`:: Specifies the stanza to configure node affinity.
+`spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution`:: Specifies a _preferred_ rule. Configure a weight and the following `preference.matchExpressions` parameters. If you want the new pod to be scheduled on the node you edited, use the same `key` and `values` parameters as the label in the node.
++
+--
+`weight`:: Specifies a weight for the node, as a number 1-100. The node with highest weight is preferred.
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`. There is no explicit _node anti-affinity_ concept, but using the `NotIn` or `DoesNotExist` operator replicates that behavior.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+--
 
 .. Create the pod.
 +

modules/nodes-scheduler-node-affinity-configuring-required.adoc

@@ -6,12 +6,13 @@
 [id="nodes-scheduler-node-affinity-configuring-required_{context}"]
 =  Configuring a required node affinity rule
 
-Required rules *must* be met before a pod can be scheduled on a node.
-
-.Procedure
+[role="_abstract"]
+You can use a _required_ rule to instruct the scheduler that the rules *must* be met before a pod can be scheduled on a node.
 
 The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler is required to place on the node.
 
+.Procedure
+
 ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 . Add a label to a node using the `oc label node` command:
 +
@@ -54,22 +55,28 @@ kind: Pod
 metadata:
   name: s1
 spec:
-  affinity: <1>
+  affinity:
     nodeAffinity:
-      requiredDuringSchedulingIgnoredDuringExecution: <2>
+      requiredDuringSchedulingIgnoredDuringExecution:
         nodeSelectorTerms:
         - matchExpressions:
-          - key: e2e-az-name <3>
+          - key: e2e-az-name
             values:
             - e2e-az1
             - e2e-az2
-            operator: In <4>
+            operator: In
 #...
 ----
-<1> Adds a pod affinity.
-<2> Configures the `requiredDuringSchedulingIgnoredDuringExecution` parameter.
-<3> Specifies the `key` and `values` that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `values` parameters as the label in the node.
-<4> Specifies an `operator`. The operator can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. For example, use the operator `In` to require the label to be in the node.
+where:
+
+`spec.affinity.nodeAffinity`:: Specifies the stanza to configure node affinity.
+`spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution`:: Specifies a _required_ rule. Configure the following `nodeSelectorTerms.matchExpressions` parameters:
++
+--
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`. There is no explicit _node anti-affinity_ concept, but using the `NotIn` or `DoesNotExist` operator replicates that behavior.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+--
 
 .. Create the pod:
 +

modules/nodes-scheduler-node-affinity-example.adoc

@@ -6,7 +6,8 @@
 [id="nodes-scheduler-node-affinity-example_{context}"]
 = Sample node affinity rules
 
-The following examples demonstrate node affinity.
+[role="_abstract"]
+You can review the following examples to a demonstration node affinity with or without matching labels.
 
 [id="admin-guide-sched-affinity-examples1_{context}"]
 == Node affinity with matching labels

modules/nodes-scheduler-pod-affinity-about.adoc

@@ -6,7 +6,8 @@
 [id="nodes-scheduler-pod-affinity-about_{context}"]
 = Understanding pod affinity
 
-_Pod affinity_ and _pod anti-affinity_ allow you to constrain which nodes your pod is eligible to be scheduled on based on the key/value labels on other pods.
+[role="_abstract"]
+You can use _pod affinity_ and _pod anti-affinity_ to constrain which nodes your pod is eligible to be scheduled on based on the key/value labels on other pods.
 
 * Pod affinity can tell the scheduler to locate a new pod on the same node as other pods if the label selector on the new pod matches the label on the current pod.
 * Pod anti-affinity can prevent the scheduler from locating a new pod on the same node as pods with the same labels if the label selector on the new pod matches the label on the current pod.
@@ -49,14 +50,14 @@ spec:
     seccompProfile:
       type: RuntimeDefault
   affinity:
-    podAffinity: <1>
-      requiredDuringSchedulingIgnoredDuringExecution: <2>
+    podAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
       - labelSelector:
           matchExpressions:
-          - key: security <3>
-            operator: In <4>
+          - key: security
+            operator: In
             values:
-            - S1 <3>
+            - S1
         topologyKey: topology.kubernetes.io/zone
   containers:
   - name: with-pod-affinity
@@ -66,11 +67,16 @@ spec:
       capabilities:
         drop: [ALL]
 ----
+where:
 
-<1> Stanza to configure pod affinity.
-<2> Defines a required rule.
-<3> The key and value (label) that must be matched to apply the rule.
-<4> The operator represents the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod.  Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`.
+`spec.affinity.podAffinity`:: Specifies a stanza to configure pod affinity.
+`spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution`:: Specifies the parameters for a _required_ rule. Configure the following `labelSelector.matchExpressions.key` parameters:
++
+--
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`.
+--
 
 .Sample `Pod` config file with pod anti-affinity
 [source,yaml]
@@ -85,14 +91,14 @@ spec:
     seccompProfile:
       type: RuntimeDefault
   affinity:
-    podAntiAffinity: <1>
-      preferredDuringSchedulingIgnoredDuringExecution: <2>
-      - weight: 100  <3>
+    podAntiAffinity:
+      preferredDuringSchedulingIgnoredDuringExecution:
+      - weight: 100
         podAffinityTerm:
           labelSelector:
             matchExpressions:
-            - key: security <4>
-              operator: In <5>
+            - key: security
+              operator: In
               values:
               - S2
           topologyKey: kubernetes.io/hostname
@@ -104,12 +110,17 @@ spec:
       capabilities:
         drop: [ALL]
 ----
-
-<1> Stanza to configure pod anti-affinity.
-<2> Defines a preferred rule.
-<3> Specifies a weight for a preferred rule. The node with the highest weight is preferred.
-<4> Description of the pod label that determines when the anti-affinity rule applies. Specify a key and value for the label.
-<5> The operator represents the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`.
+where:
+
+`spec.affinity.podAffinity`:: Specifies a stanza to configure pod affinity.
+`spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution`:: Specifies the parameters for a _preferred_ rule. Configure a weight and the following `podAffinityTerm.labelSelector.matchExpressions` parameters:
++
+--
+`weight`:: Specifies the weight for a preferred rule. The node with the highest weight is preferred.
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`values`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`.
+--
 
 [NOTE]
 ====

modules/nodes-scheduler-pod-affinity-configuring.adoc

@@ -6,7 +6,8 @@
 [id="nodes-scheduler-pod-affinity-configuring_{context}"]
 = Configuring a pod affinity rule
 
-The following steps demonstrate a simple two-pod configuration that creates pod with a label and a pod that uses affinity to allow scheduling with that pod.
+[role="_abstract"]
+You can use the following example pod specifications to create a pod with a label and a pod that uses affinity to allow scheduling with that pod.
 
 [NOTE]
 ====
@@ -60,25 +61,30 @@ metadata:
   name: security-s1-east
 # ...
 spec:
-  affinity: <1>
+  affinity:
     podAffinity:
-      requiredDuringSchedulingIgnoredDuringExecution: <2>
+      requiredDuringSchedulingIgnoredDuringExecution:
       - labelSelector:
           matchExpressions:
-          - key: security <3>
+          - key: security
             values:
             - S1
-            operator: In <4>
-        topologyKey: topology.kubernetes.io/zone <5>
+            operator: In
+        topologyKey: topology.kubernetes.io/zone
 # ...
 ----
+where:
+
+`spec.affinity.podAffinity`:: Specifies a stanza to configure pod affinity.
+`spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution`:: Specifies the parameters for a _required_ rule. Alternatively, you can configure a _preferred_ rule by using the `preferredDuringSchedulingIgnoredDuringExecution` parmeter. 
++
+Configure the following `labelSelector.matchExpressions` parameters. If you want the new pod to be scheduled with the other pod, use the same `key` and `values` parameters as the label on the first pod.
 +
 --
-<1> Adds a pod affinity.
-<2> Configures the `requiredDuringSchedulingIgnoredDuringExecution` parameter or the `preferredDuringSchedulingIgnoredDuringExecution` parameter.
-<3> Specifies the `key` and `values` that must be met. If you want the new pod to be scheduled with the other pod, use the same `key` and `values` parameters as the label on the first pod.
-<4> Specifies an `operator`. The operator can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. For example, use the operator `In` to require the label to be in the node.
-<5> Specify a `topologyKey`, which is a prepopulated link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#interlude-built-in-node-labels[Kubernetes label] that the system uses to denote such a topology domain.
+`key`:: Specifies the key of the key/value pair (label) that must be matched to apply the rule.
+`value`:: Specifies the value of the key/value pair (label) that must be matched to apply the rule.
+`operator`:: Specifies the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`.
+`topologyKey`:: Specifies a prepopulated Kubernetes label that the system uses to denote such a topology domain.
 --
 
 .. Create the pod.

modules/nodes-scheduler-pod-affinity-example.adoc

@@ -6,7 +6,8 @@
 [id="nodes-scheduler-pod-affinity-example_{context}"]
 = Sample pod affinity and anti-affinity rules
 
-The following examples demonstrate pod affinity and pod anti-affinity.
+[role="_abstract"]
+Use these configuration examples to understand how matching labels, non-matching labels, and specific label selectors affect how the cluster schedules pods onto nodes.
 
 [id="nodes-scheduler-pod-affinity-example-affinity_{context}"]
 == Pod Affinity