From 9120e0c7d2d26b177ecc0535e9836373d9df83a7 Mon Sep 17 00:00:00 2001
From: Keita Mochizuki <37737691+mochizuki875@users.noreply.github.com>
Date: Fri, 21 Mar 2025 10:59:18 +0900
Subject: [PATCH] Revert "Update the description of TopologySpreadConstraints's
 matchLabelKeys to align with the design change"

---
 .../topology-spread-constraints.md            | 24 +++++++------------
 1 file changed, 9 insertions(+), 15 deletions(-)

diff --git a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md
index f7638e64cf160..78b94834a0356 100644
--- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md
+++ b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md
@@ -131,24 +131,18 @@ 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 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 >}}
+- **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`.
 
   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. For example, if you are configuring a Deployment, you can use the label keyed with
+  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.