Merge pull request #21689 from alculquicondor/default-spreading

Docs for new default PodTopologySpread functionality and gate

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

@@ -186,7 +186,7 @@ There are some implicit conventions worth noting here:
 
 ### Cluster-level default constraints
 
-{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
+{{< feature-state for_k8s_version="v1.19" state="beta" >}}
 
 It is possible to set default topology spread constraints for a cluster. Default
 topology spread constraints are applied to a Pod if, and only if:
@@ -203,7 +203,7 @@ replication controllers, replica sets or stateful sets that the Pod belongs to.
 An example configuration might look like follows:
 
 ```yaml
-apiVersion: kubescheduler.config.k8s.io/v1alpha2
+apiVersion: kubescheduler.config.k8s.io/v1beta1
 kind: KubeSchedulerConfiguration
 
 profiles:
@@ -212,18 +212,49 @@ profiles:
       args:
         defaultConstraints:
           - maxSkew: 1
-            topologyKey: failure-domain.beta.kubernetes.io/zone
+            topologyKey: topology.kubernetes.io/zone
             whenUnsatisfiable: ScheduleAnyway
 ```
 
 {{< note >}}
 The score produced by default scheduling constraints might conflict with the
 score produced by the
-[`DefaultPodTopologySpread` plugin](/docs/reference/scheduling/config/#scheduling-plugins).
+[`SelectorSpread` plugin](/docs/reference/scheduling/config/#scheduling-plugins).
 It is recommended that you disable this plugin in the scheduling profile when
 using default constraints for `PodTopologySpread`.
 {{< /note >}}
 
+#### Internal default constraints
+
+{{< feature-state for_k8s_version="v1.19" state="alpha" >}}
+
+When you enable the `DefaultPodTopologySpread` feature gate, the
+legacy `SelectorSpread` plugin is disabled.
+kube-scheduler uses the following default topology constraints for the
+`PodTopologySpread` plugin configuration:
+
+```yaml
+defaultConstraints:
+  - maxSkew: 3
+    topologyKey: "kubernetes.io/hostname"
+    whenUnsatisfiable: ScheduleAnyway
+  - maxSkew: 5
+    topologyKey: "topology.kubernetes.io/zone"
+    whenUnsatisfiable: ScheduleAnyway
+```
+
+Also, the legacy `SelectorSpread` plugin, which provides an equivalent behavior,
+is disabled.
+
+{{< note >}}
+If your nodes are not expected to have **both** `kubernetes.io/hostname` and
+`topology.kubernetes.io/zone` labels set, define your own constraints
+instead of using the Kubernetes defaults.
+
+The `PodTopologySpread` plugin does not score the nodes that don't have
+the topology keys specified in the spreading constraints.
+{{< /note >}}
+
 ## Comparison with PodAffinity/PodAntiAffinity
 
 In Kubernetes, directives related to "Affinity" control how Pods are
@@ -240,8 +271,6 @@ workloads and scaling out replicas smoothly. See [Motivation](https://github.com
 
 ## Known Limitations
 
-As of 1.18, at which this feature is Beta, there are some known limitations:
-
 - Scaling down a Deployment may result in imbalanced Pods distribution.
 - Pods matched on tainted nodes are respected. See [Issue 80921](https://github.com/kubernetes/kubernetes/issues/80921)
 

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

@@ -80,6 +80,7 @@ different Kubernetes components.
 | `CustomCPUCFSQuotaPeriod` | `false` | Alpha | 1.12 | |
 | `CustomResourceDefaulting` | `false` | Alpha| 1.15 | 1.15 |
 | `CustomResourceDefaulting` | `true` | Beta | 1.16 | |
+| `DefaultPodTopologySpread` | `false` | Alpha | 1.19 | |
 | `DevicePlugins` | `false` | Alpha | 1.8 | 1.9 |
 | `DevicePlugins` | `true` | Beta | 1.10 | |
 | `DryRun` | `false` | Alpha | 1.12 | 1.12 |
@@ -406,6 +407,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
   troubleshoot a running Pod.
 - `DevicePlugins`: Enable the [device-plugins](/docs/concepts/cluster-administration/device-plugins/)
   based resource provisioning on nodes.
+- `DefaultPodTopologySpread`: Enables the use of `PodTopologySpread` scheduling plugin to do
+  [default spreading](/docs/concepts/workloads/pods/pod/pod-topology-spread-constraints/#internal-default-constraints).
 - `DryRun`: Enable server-side [dry run](/docs/reference/using-api/api-concepts/#dry-run) requests
   so that validation, merging, and mutation can be tested without committing.
 - `DynamicAuditing`: Enable [dynamic auditing](/docs/tasks/debug-application-cluster/audit/#dynamic-backend)