Merge pull request #53111 from andrewsykim/pod-topology-labels-1-35

add docs for PodTopologyLabelsAdmission feature

Author: k8s-ci-robot

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

@@ -675,6 +675,34 @@ overall utilization.
 Read [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
 to learn more about how these work.
 
+## Pod topology labels
+
+{{< feature-state feature_gate_name="PodTopologyLabelsAdmission" >}}
+
+Pods inherit the topology labels (`topology.kubernetes.io/zone` and `topology.kubernetes.io/region`) from their assigned Node if those labels are present. These labels can then be utilized via the Downward API to provide the workload with node topology awareness.
+
+Here is an example of a Pod using downward API for it's zone and region:
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod-with-topology-labels
+spec:
+  containers:
+    - name: app
+      image: alpine
+      command: ["sh", "-c", "env"]
+      env:
+        - name: MY_ZONE
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.labels['topology.kubernetes.io/zone']
+        - name: MY_REGION
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.labels['topology.kubernetes.io/region']
+```
+
 ## Operators
 
 The following are all the logical operators that you can use in the `operator` field for `nodeAffinity` and `podAffinity` mentioned above.

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

@@ -9,6 +9,10 @@ stages:
   - stage: alpha 
     defaultValue: false
     fromVersion: "1.33"
+    toVersion: "1.34"
+  - stage: beta
+    defaultValue: true
+    fromVersion: "1.35"
 ---
 Enables the `PodTopologyLabels` admission plugin.
 See [Pod Topology Labels](docs/reference/access-authn-authz/admission-controllers#podtopologylabels)