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 review

content/en/docs/concepts/scheduling-eviction/assign-pod-node.md

@@ -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

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -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