Merge pull request #33792 from sftim/20220510_assign_pod_node_affinity_updates

Revise scheduling-related docs

Author: k8s-ci-robot

content/en/blog/_posts/2020-05-05-introducing-podtopologyspread.md

@@ -67,7 +67,7 @@ Let's see an example of a cluster to understand this API.
 As the feature name "PodTopologySpread" implies, the basic usage of this feature
 is to run your workload with an absolute even manner (maxSkew=1), or relatively
 even manner (maxSkew>=2). See the [official
-document](/docs/concepts/workloads/pods/pod-topology-spread-constraints/)
+document](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
 for more details.
 
 In addition to this basic usage, there are some advanced usage examples that

content/en/blog/_posts/2020-09-30-writing-crl-scheduler/index.md

@@ -70,7 +70,7 @@ To correct the latter issue, we now employ a "hunt and peck" approach to removin
 ### 1. Upgrade to kubernetes 1.18 and make use of Pod Topology Spread Constraints
 
 While this seems like it could have been the perfect solution, at the time of writing Kubernetes 1.18 was unavailable on the two most common managed Kubernetes services in public cloud, EKS and GKE.
-Furthermore, [pod topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/) were still a [beta feature in 1.18](https://v1-18.docs.kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/) which meant that it [wasn't guaranteed to be available in managed clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#kubernetes_feature_choices) even when v1.18 became available.
+Furthermore, [pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/) were still a beta feature in 1.18 which meant that it [wasn't guaranteed to be available in managed clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#kubernetes_feature_choices) even when v1.18 became available.
 The entire endeavour was concerningly reminiscent of checking [caniuse.com](https://caniuse.com/) when Internet Explorer 8 was still around.
 
 ### 2. Deploy a statefulset _per zone_.

content/en/docs/concepts/scheduling-eviction/_index.md

@@ -23,6 +23,7 @@ of terminating one or more Pods on Nodes.
 * [Kubernetes Scheduler](/docs/concepts/scheduling-eviction/kube-scheduler/)
 * [Assigning Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)
 * [Pod Overhead](/docs/concepts/scheduling-eviction/pod-overhead/)
+* [Pod Topology Spread Constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
 * [Taints and Tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/)
 * [Scheduling Framework](/docs/concepts/scheduling-eviction/scheduling-framework)
 * [Scheduler Performance Tuning](/docs/concepts/scheduling-eviction/scheduler-perf-tuning/)

content/en/docs/concepts/scheduling-eviction/assign-pod-node.md

@@ -11,24 +11,27 @@ weight: 20
 
 <!-- overview -->
 
-You can constrain a {{< glossary_tooltip text="Pod" term_id="pod" >}} so that it can only run on particular set of
-{{< glossary_tooltip text="node(s)" term_id="node" >}}.
+You can constrain a {{< glossary_tooltip text="Pod" term_id="pod" >}} so that it is 
+_restricted_ to run on particular {{< glossary_tooltip text="node(s)" term_id="node" >}},
+or to _prefer_ to run on particular nodes.
 There are several ways to do this and the recommended approaches all use
 [label selectors](/docs/concepts/overview/working-with-objects/labels/) to facilitate the selection.
-Generally such constraints are unnecessary, as the scheduler will automatically do a reasonable placement
+Often, you do not need to set any such constraints; the
+{{< glossary_tooltip text="scheduler" term_id="kube-scheduler" >}}  will automatically do a reasonable placement
 (for example, spreading your Pods across nodes so as not place Pods on a node with insufficient free resources).
 However, there are some circumstances where you may want to control which node
-the Pod deploys to, for example, to ensure that a Pod ends up on a node with an SSD attached to it, or to co-locate Pods from two different
-services that communicate a lot into the same availability zone.
+the Pod deploys to, for example, to ensure that a Pod ends up on a node with an SSD attached to it,
+or to co-locate Pods from two different services that communicate a lot into the same availability zone.
 
 <!-- body -->
 
 You can use any of the following methods to choose where Kubernetes schedules
-specific Pods: 
+specific Pods:
 
   * [nodeSelector](#nodeselector) field matching against [node labels](#built-in-node-labels)
   * [Affinity and anti-affinity](#affinity-and-anti-affinity)
   * [nodeName](#nodename) field
+  * [Pod topology spread constraints](#pod-topology-spread-constraints)
 
 ## Node labels {#built-in-node-labels}
 
@@ -337,13 +340,15 @@ null `namespaceSelector` matches the namespace of the Pod where the rule is defi
 Inter-pod affinity and anti-affinity can be even more useful when they are used with higher
 level collections such as ReplicaSets, StatefulSets, Deployments, etc.  These
 rules allow you to configure that a set of workloads should
-be co-located in the same defined topology, eg., the same node.
+be co-located in the same defined topology; for example, preferring to place two related
+Pods onto the same node.
 
-Take, for example, a three-node cluster running a web application with an
-in-memory cache like redis. You could use inter-pod affinity and anti-affinity
-to co-locate the web servers with the cache as much as possible.
+For example: imagine a three-node cluster. You use the cluster to run a web application
+and also an in-memory cache (such as Redis). For this example, also assume that latency between
+the web application and the memory cache should be as low as is practical. You could use inter-pod
+affinity and anti-affinity to co-locate the web servers with the cache as much as possible.
 
-In the following example Deployment for the redis cache, the replicas get the label `app=store`. The
+In the following example Deployment for the Redis cache, the replicas get the label `app=store`. The
 `podAntiAffinity` rule tells the scheduler to avoid placing multiple replicas
 with the `app=store` label on a single node. This creates each cache in a
 separate node.
@@ -378,10 +383,10 @@ spec:
         image: redis:3.2-alpine
 ```
 
-The following Deployment for the web servers creates replicas with the label `app=web-store`. The
-Pod affinity rule tells the scheduler to place each replica on a node that has a
-Pod with the label `app=store`. The Pod anti-affinity rule tells the scheduler
-to avoid placing multiple `app=web-store` servers on a single node.
+The following example Deployment for the web servers creates replicas with the label `app=web-store`.
+The Pod affinity rule tells the scheduler to place each replica on a node that has a Pod
+with the label `app=store`. The Pod anti-affinity rule tells the scheduler never to place
+multiple `app=web-store` servers on a single node.
 
 ```yaml
 apiVersion: apps/v1
@@ -430,6 +435,10 @@ where each web server is co-located with a cache, on three separate nodes.
 | *webserver-1*        |   *webserver-2*     |    *webserver-3*   |
 |  *cache-1*           |     *cache-2*       |     *cache-3*      |
 
+The overall effect is that each cache instance is likely to be accessed by a single client, that
+is running on the same node. This approach aims to minimize both skew (imbalanced load) and latency.
+
+You might have other reasons to use Pod anti-affinity.
 See the [ZooKeeper tutorial](/docs/tutorials/stateful-application/zookeeper/#tolerating-node-failure)
 for an example of a StatefulSet configured with anti-affinity for high
 availability, using the same technique as this example.
@@ -468,6 +477,16 @@ spec:
 
 The above Pod will only run on the node `kube-01`.
 
+## Pod topology spread constraints
+
+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, or among any other
+topology domains that you define. You might do this to improve performance, expected availability, or
+overall utilization.
+
+Read [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
+to learn more about how these work.
+
 ## {{% heading "whatsnext" %}}
 
 * Read more about [taints and tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/) .

content/en/docs/concepts/scheduling-eviction/kube-scheduler.md

@@ -83,7 +83,7 @@ of the scheduler:
 ## {{% heading "whatsnext" %}}
 
 * Read about [scheduler performance tuning](/docs/concepts/scheduling-eviction/scheduler-perf-tuning/)
-* Read about [Pod topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/)
+* Read about [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
 * Read the [reference documentation](/docs/reference/command-line-tools-reference/kube-scheduler/) for kube-scheduler
 * Read the [kube-scheduler config (v1beta3)](/docs/reference/config-api/kube-scheduler-config.v1beta3/) reference
 * Learn about [configuring multiple schedulers](/docs/tasks/extend-kubernetes/configure-multiple-schedulers/)