add: the doc for matchLabelKeys/mismatchLabelKeys in pod (anti)affinity (#43812)
* add: the doc for matchLabelKeys/mismatchLabelKeys in pod (anti)affinity * fix based on reviews * add the explanation for labelSelector * address the reviewpull/43600/head
Kensei Nakada
GitHub
parent
b8b45ee9c9
commit
2ec25fbe7b
|
|
@ -358,6 +358,108 @@ The affinity term is applied to namespaces selected by both `namespaceSelector`
|
|||
Note that an empty `namespaceSelector` ({}) matches all namespaces, while a null or empty `namespaces` list and
|
||||
null `namespaceSelector` matches the namespace of the Pod where the rule is defined.
|
||||
|
||||
#### matchLabelKeys
|
||||
|
||||
{{< feature-state for_k8s_version="v1.29" state="alpha" >}}
|
||||
|
||||
{{< note >}}
|
||||
<!-- UPDATE THIS WHEN PROMOTING TO BETA -->
|
||||
The `matchLabelKeys` field is a alpha-level field and is disabled by default in
|
||||
Kubernetes {{< skew currentVersion >}}.
|
||||
When you want to use it, you have to enable it via the
|
||||
`MatchLabelKeysInPodAffinity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
|
||||
{{< /note >}}
|
||||
|
||||
Kubernetes includes an optional `matchLabelKeys` field for Pod affinity
|
||||
or anti-affinity. The field specifies keys for the labels that should match with the incoming Pod's labels,
|
||||
when satisfying the Pod (anti)affinity.
|
||||
|
||||
The keys are used to look up values from the pod labels; those key-value labels are combined
|
||||
(using `AND`) with the match restrictions defined using the `labelSelector` field. The combined
|
||||
filtering selects the set of existing pods that will be taken into Pod (anti)affinity calculation.
|
||||
|
||||
A common use case is to use `matchLabelKeys` with `pod-template-hash` (set on Pods
|
||||
managed as part of a Deployment, where the value is unique for each revision).
|
||||
Using `pod-template-hash` in `matchLabelKeys` allows you to target the Pods that belong
|
||||
to the same revision as the incoming Pod, so that a rolling upgrade won't break affinity.
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: application-server
|
||||
...
|
||||
spec:
|
||||
template:
|
||||
affinity:
|
||||
podAffinity:
|
||||
requiredDuringSchedulingIgnoredDuringExecution:
|
||||
- labelSelector:
|
||||
matchExpressions:
|
||||
- key: app
|
||||
operator: In
|
||||
values:
|
||||
- database
|
||||
topologyKey: topology.kubernetes.io/zone
|
||||
# Only Pods from a given rollout are taken into consideration when calculating pod affinity.
|
||||
# If you update the Deployment, the replacement Pods follow their own affinity rules
|
||||
# (if there are any defined in the new Pod template)
|
||||
matchLabelKeys:
|
||||
- pod-template-hash
|
||||
```
|
||||
|
||||
#### mismatchLabelKeys
|
||||
|
||||
{{< feature-state for_k8s_version="v1.29" state="alpha" >}}
|
||||
|
||||
{{< note >}}
|
||||
<!-- UPDATE THIS WHEN PROMOTING TO BETA -->
|
||||
The `mismatchLabelKeys` field is a alpha-level field and is disabled by default in
|
||||
Kubernetes {{< skew currentVersion >}}.
|
||||
When you want to use it, you have to enable it via the
|
||||
`MatchLabelKeysInPodAffinity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
|
||||
{{< /note >}}
|
||||
|
||||
Kubernetes includes an optional `mismatchLabelKeys` field for Pod affinity
|
||||
or anti-affinity. The field specifies keys for the labels that should **not** match with the incoming Pod's labels,
|
||||
when satisfying the Pod (anti)affinity.
|
||||
|
||||
One example use case is to ensure Pods go to the topology domain (node, zone, etc) where only Pods from the same tenant or team are scheduled in.
|
||||
In other words, you want to avoid running Pods from two different tenants on the same topology domain at the same time.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
labels:
|
||||
# Assume that all relevant Pods have a "tenant" label set
|
||||
tenant: tenant-a
|
||||
...
|
||||
spec:
|
||||
affinity:
|
||||
podAffinity:
|
||||
requiredDuringSchedulingIgnoredDuringExecution:
|
||||
# ensure that pods associated with this tenant land on the correct node pool
|
||||
- matchLabelKeys:
|
||||
- tenant
|
||||
topologyKey: node-pool
|
||||
podAntiAffinity:
|
||||
requiredDuringSchedulingIgnoredDuringExecution:
|
||||
# ensure that pods associated with this tenant can't schedule to nodes used for another tenant
|
||||
- mismatchLabelKeys:
|
||||
- tenant # whatever the value of the "tenant" label for this Pod, prevent
|
||||
# scheduling to nodes in any pool where any Pod from a different
|
||||
# tenant is running.
|
||||
labelSelector:
|
||||
# We have to have the labelSelector which selects only Pods with the tenant label,
|
||||
# otherwise this Pod would hate Pods from daemonsets as well, for example,
|
||||
# which aren't supposed to have the tenant label.
|
||||
matchExpressions:
|
||||
- key: tenant
|
||||
operator: Exists
|
||||
topologyKey: node-pool
|
||||
```
|
||||
|
||||
#### More practical use-cases
|
||||
|
||||
Inter-pod affinity and anti-affinity can be even more useful when they are used with higher
|
||||
|
|
|
|||
|
|
@ -136,6 +136,7 @@ For a reference to old feature gates that are removed, please refer to
|
|||
| `LogarithmicScaleDown` | `true` | Beta | 1.22 | |
|
||||
| `LoggingAlphaOptions` | `false` | Alpha | 1.24 | - |
|
||||
| `LoggingBetaOptions` | `true` | Beta | 1.24 | - |
|
||||
| `MatchLabelKeysInPodAffinity` | `false` | Alpha | 1.29 | - |
|
||||
| `MatchLabelKeysInPodTopologySpread` | `false` | Alpha | 1.25 | 1.26 |
|
||||
| `MatchLabelKeysInPodTopologySpread` | `true` | Beta | 1.27 | - |
|
||||
| `MaxUnavailableStatefulSet` | `false` | Alpha | 1.24 | |
|
||||
|
|
@ -627,6 +628,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
|||
based on logarithmic bucketing of pod timestamps.
|
||||
- `LoggingAlphaOptions`: Allow fine-tuing of experimental, alpha-quality logging options.
|
||||
- `LoggingBetaOptions`: Allow fine-tuing of experimental, beta-quality logging options.
|
||||
- `MatchLabelKeysInPodAffinity`: Enable the `matchLabelKeys` and `mismatchLabelKeys` field for
|
||||
[pod (anti)affinity](/docs/concepts/scheduling-eviction/assign-pod-node/).
|
||||
- `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
|
||||
|
|
|
|||
Loading…
Reference in New Issue