From cce49fe7e65b316bd188095d6b0a5c3a87f95098 Mon Sep 17 00:00:00 2001 From: Alex Wang Date: Tue, 9 Aug 2022 10:59:16 +0800 Subject: [PATCH] add doc for MatchLabelKeysInPodTopologySpread Signed-off-by: Alex Wang --- .../topology-spread-constraints.md | 22 +++++++++++++++++++ .../feature-gates.md | 3 +++ 2 files changed, 25 insertions(+) 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 77f4d1ea55..2a56eafdf8 100644 --- a/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md +++ b/content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md @@ -64,6 +64,7 @@ spec: topologyKey: whenUnsatisfiable: labelSelector: + matchLabelKeys: # optional; alpha since v1.25 ### other Pod fields go here ``` @@ -123,6 +124,27 @@ 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. 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. + + ```yaml + topologySpreadConstraints: + - maxSkew: 1 + topologyKey: kubernetes.io/hostname + whenUnsatisfiable: DoNotSchedule + matchLabelKeys: + - app + - pod-template-hash + ``` + + {{< note >}} + The `matchLabelKeys` field is an alpha field added in 1.25. You have to enable the + `MatchLabelKeysInPodTopologySpread` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) + in order to use it. + {{< /note >}} + When a Pod defines more than one `topologySpreadConstraint`, those constraints are combined using a logical AND operation: the kube-scheduler looks for a node for the incoming Pod that satisfies all the configured constraints. diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 0771736f4f..b155cb05ce 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -146,6 +146,7 @@ different Kubernetes components. | `LocalStorageCapacityIsolationFSQuotaMonitoring` | `false` | Alpha | 1.15 | | | `LogarithmicScaleDown` | `false` | Alpha | 1.21 | 1.21 | | `LogarithmicScaleDown` | `true` | Beta | 1.22 | | +| `MatchLabelKeysInPodTopologySpread` | `false` | Alpha | 1.25 | | | `MaxUnavailableStatefulSet` | `false` | Alpha | 1.24 | | | `MemoryManager` | `false` | Alpha | 1.21 | 1.21 | | `MemoryManager` | `true` | Beta | 1.22 | | @@ -987,6 +988,8 @@ Each feature gate is designed for enabling/disabling a specific feature: filesystem walk for better performance and accuracy. - `LogarithmicScaleDown`: Enable semi-random selection of pods to evict on controller scaledown based on logarithmic bucketing of pod timestamps. +- `MatchLabelKeysInPodTopologySpread`: Enable the `matchLabelKeys` field for + [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/). - `MaxUnavailableStatefulSet`: Enables setting the `maxUnavailable` field for the [rolling update strategy](/docs/concepts/workloads/controllers/statefulset/#rolling-updates) of a StatefulSet. The field specifies the maximum number of Pods