Merge pull request #27377 from sftim/20210401_namespace_default_label_name_tweaks

Improve docs for NamespaceDefaultLabelName

content/en/docs/concepts/overview/working-with-objects/namespaces.md

@@ -30,7 +30,7 @@ Namespaces are a way to divide cluster resources between multiple users (via [re
 
 It is not necessary to use multiple namespaces to separate slightly different
 resources, such as different versions of the same software: use
-[labels](/docs/concepts/overview/working-with-objects/labels) to distinguish
+{{< glossary_tooltip text="labels" term_id="label" >}} to distinguish
 resources within the same namespace.
 
 ## Working with Namespaces
@@ -114,6 +114,16 @@ kubectl api-resources --namespaced=true
 kubectl api-resources --namespaced=false
 ```
 
+## Automatic labelling
+
+{{< feature-state state="beta" for_k8s_version="1.21" >}}
+
+The Kubernetes control plane sets an immutable {{< glossary_tooltip text="label" term_id="label" >}}
+`kubernetes.io/metadata.name` on all namespaces, provided that the `NamespaceDefaultLabelName`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled.
+The value of the label is the namespace name.
+
+
 ## {{% heading "whatsnext" %}}
 
 * Learn more about [creating a new namespace](/docs/tasks/administer-cluster/namespaces/#creating-a-new-namespace).

content/en/docs/concepts/services-networking/network-policies.md

@@ -266,14 +266,19 @@ supports the `endPort` field in NetworkPolicy specifications.
 
 ## Targeting a Namespace by its name
 
-As of Kubernetes v1.21, an immutable label `kubernetes.io/metadata.name` is added to all
-namespaces. The value of the label is the namespace name. While NetworkPolicy cannot
-target a namespace by its name with some object field, this label now can be used to target
-a specific namespace.
+{{< feature-state state="beta" for_k8s_version="1.21" >}}
+
+The Kubernetes control plane sets an immutable label `kubernetes.io/metadata.name` on all
+namespaces, provided that the `NamespaceDefaultLabelName`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled.
+The value of the label is the namespace name.
+
+While NetworkPolicy cannot target a namespace by its name with some object field, you can use the
+standardized label to target a specific namespace.
 
 ## What you can't do with network policies (at least, not yet)
 
-As of Kubernetes 1.20, the following functionality does not exist in the NetworkPolicy API, but you might be able to implement workarounds using Operating System components (such as SELinux, OpenVSwitch, IPTables, and so on) or Layer 7 technologies (Ingress controllers, Service Mesh implementations) or admission controllers.  In case you are new to network security in Kubernetes, its worth noting that the following User Stories cannot (yet) be implemented using the NetworkPolicy API.  Some (but not all) of these user stories are actively being discussed for future releases of the NetworkPolicy API.
+As of Kubernetes {{< skew latestVersion >}}, the following functionality does not exist in the NetworkPolicy API, but you might be able to implement workarounds using Operating System components (such as SELinux, OpenVSwitch, IPTables, and so on) or Layer 7 technologies (Ingress controllers, Service Mesh implementations) or admission controllers.  In case you are new to network security in Kubernetes, its worth noting that the following User Stories cannot (yet) be implemented using the NetworkPolicy API.
 
 - Forcing internal cluster traffic to go through a common gateway (this might be best served with a service mesh or other proxy).
 - Anything TLS related (use a service mesh or ingress controller for this).

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

@@ -704,7 +704,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
   the volume mounter.
 - `MountPropagation`: Enable sharing volume mounted by one container to other containers or pods.
   For more details, please see [mount propagation](/docs/concepts/storage/volumes/#mount-propagation).
-- `NamespaceDefaultLabelName`: Enable the API Server to create a default label `kubernetes.io/metadata.name` in all namespaces containing the namespace name.
+- `NamespaceDefaultLabelName`: Configure the API Server to set an immutable {{< glossary_tooltip text="label" term_id="label" >}}
+  `kubernetes.io/metadata.name` on all namespaces, containing the namespace name.
 - `NetworkPolicyEndPort`: Enable use of the field `endPort` in NetworkPolicy objects, allowing the selection of a port range instead of a single port.
 - `NodeDisruptionExclusion`: Enable use of the Node label `node.kubernetes.io/exclude-disruption`
   which prevents nodes from being evacuated during zone failures.

content/en/docs/reference/labels-annotations-taints.md

@@ -36,7 +36,13 @@ Example: `kubernetes.io/metadata.name=mynamespace`
 
 Used on: Namespaces
 
-Kubernetes API Server defaults this label to the namespace name during admission. This label can be used with any namespace selector, as an example with NetworkPolicy objects.
+When the `NamespaceDefaultLabelName`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled,
+the Kubernetes API server sets this label on all namespaces. The label value is set to
+the name of the namespace.
+
+This is useful if you want to target a specific namespace with a label
+{{< glossary_tooltip text="selector" term_id="selector" >}}.
 
 ## beta.kubernetes.io/arch (deprecated)