Merge pull request #40008 from denkensk/update-match

doc: forbid to set matchLabelKeys when labelSelector isn’t set in topologySpreadConstraints

Author: k8s-ci-robot

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md

@@ -129,17 +129,30 @@ your cluster. Those fields are:
   for more details.
 
 - **matchLabelKeys** is a list of pod label keys to select the pods over which
-  spreading will be calculated. The keys are used to lookup values from the pod labels, those key-value labels are ANDed with `labelSelector` to select the group of existing pods over which spreading will be calculated for the incoming pod. Keys that don't exist in the pod labels will be ignored. A null or empty list means only match against the `labelSelector`.
-
-  With `matchLabelKeys`, users don't need to update the `pod.spec` between different revisions. The controller/operator just needs to set different values to the same `label` key for different revisions. The scheduler will assume the values automatically based on `matchLabelKeys`. For example, if users use Deployment, they can use the label keyed with `pod-template-hash`, which is added automatically by the Deployment controller, to distinguish between different revisions in a single Deployment.
+  spreading will be calculated. The keys are used to lookup values from the pod labels,
+  those key-value labels are ANDed with `labelSelector` to select the group of existing
+  pods over which spreading will be calculated for the incoming pod. The same key is
+  forbidden to exist in both `matchLabelKeys` and `labelSelector`. `matchLabelKeys` cannot
+  be set when `labelSelector` isn't set. Keys that don't exist in the pod labels will be
+  ignored. A null or empty list means only match against the `labelSelector`.
+
+  With `matchLabelKeys`, you don't need to update the `pod.spec` between different revisions.
+  The controller/operator just needs to set different values to the same label key for different
+  revisions. The scheduler will assume the values automatically based on `matchLabelKeys`. For
+  example, if you are configuring a Deployment, you can use the label keyed with
+  [pod-template-hash](/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label), which
+  is added automatically by the Deployment controller, to distinguish between different revisions
+  in a single Deployment.
 
   ```yaml
       topologySpreadConstraints:
           - maxSkew: 1
             topologyKey: kubernetes.io/hostname
             whenUnsatisfiable: DoNotSchedule
+            labelSelector:
+              matchLabels:
+                app: foo
             matchLabelKeys:
-              - app
               - pod-template-hash
   ```