Merge pull request #49607 from mochizuki875/add_deprecation_matchlabelkeys_podtopologyspread

Update the description of TopologySpreadConstraints's matchLabelKeys to align with the design change

Author: k8s-ci-robot

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

@@ -131,18 +131,24 @@ your cluster. Those fields are:
   See [Label Selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors)
   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. 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`.
+- **matchLabelKeys** is a list of pod label keys to select the group of pods over which 
+  the spreading skew will be calculated. At a pod creation, 
+  the kube-apiserver uses those keys to lookup values from the incoming pod labels,
+  and those key-value labels will be merged with any existing `labelSelector`.
+  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`.
+
+  {{< caution >}}
+  It's not recommended to use `matchLabelKeys` with labels that might be updated directly on pods.
+  Even if you edit the pod's label that is specified at `matchLabelKeys` **directly**, (that is, not via a deployment),
+  kube-apiserver doesn't reflect the label update onto the merged `labelSelector`.
+  {{< /caution >}}
 
   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
+  revisions. 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.