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)