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 935ab1c7a9176..4248c9d8387ef 100644 --- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md +++ b/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.