From 7a4fbbce519c9587dc60e897e586fc8f1d062153 Mon Sep 17 00:00:00 2001 From: mochizuki875 Date: Fri, 31 Jan 2025 08:15:45 +0000 Subject: [PATCH 1/4] Update the description of matchLabelKeys to align with the design change --- .../topology-spread-constraints.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 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 935ab1c7a9176..724c31ba9fae9 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,20 @@ 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, + apiserver will use those keys to lookup values from the incoming pod labels, + and those key-value labels will be merged with 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`. + It's not recommended to use `matchLabelKeys` with labels that might be updated + because the update of the label isn't reflected onto the merged `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 + 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. From bf53e4f1ee151aa2181afacce2342f6e66b7ba54 Mon Sep 17 00:00:00 2001 From: mochizuki875 Date: Fri, 31 Jan 2025 08:51:21 +0000 Subject: [PATCH 2/4] fix1 --- .../scheduling-eviction/topology-spread-constraints.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 724c31ba9fae9..eac12e70de137 100644 --- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md +++ b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md @@ -139,8 +139,11 @@ your cluster. Those fields are: `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`. + + {{< warning >}} It's not recommended to use `matchLabelKeys` with labels that might be updated - because the update of the label isn't reflected onto the merged `LabelSelector`. + because the update of the label isn't reflected onto the merged `labelSelector`. + {{< /warning >}} 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 From ea2bd426517f72b30721a46f82c8594c84d7b235 Mon Sep 17 00:00:00 2001 From: mochizuki875 Date: Fri, 31 Jan 2025 12:40:18 +0000 Subject: [PATCH 3/4] fix2 --- .../scheduling-eviction/topology-spread-constraints.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 eac12e70de137..abba4ef7a3ce4 100644 --- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md +++ b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md @@ -133,17 +133,17 @@ your cluster. Those fields are: - **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, - apiserver will use those keys to lookup values from the incoming pod labels, - and those key-value labels will be merged with existing `labelSelector`. + 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`. - {{< warning >}} + {{< caution >}} It's not recommended to use `matchLabelKeys` with labels that might be updated because the update of the label isn't reflected onto the merged `labelSelector`. - {{< /warning >}} + {{< /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 From 3c587f39e875bc5471a43930f077da9d3e33c05b Mon Sep 17 00:00:00 2001 From: mochizuki875 Date: Sat, 1 Feb 2025 17:28:14 +0000 Subject: [PATCH 4/4] fix3 --- .../scheduling-eviction/topology-spread-constraints.md | 5 +++-- 1 file changed, 3 insertions(+), 2 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 abba4ef7a3ce4..4248c9d8387ef 100644 --- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md +++ b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md @@ -141,8 +141,9 @@ your cluster. Those fields are: 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 - because the update of the label isn't reflected onto the merged `labelSelector`. + 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.