Add documentation about user namespaces and PSS

Adding required documentation for
[KEP-127](kubernetes/enhancements#127).

Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
Signed-off-by: Rodrigo Campos <rodrigoca@microsoft.com>
Co-authored-by: Tim Bannister <tim@scalefactory.com>
Signed-off-by: Sascha Grunert <sgrunert@redhat.com>

content/en/docs/concepts/workloads/pods/user-namespaces.md

@@ -152,6 +152,35 @@ host's file owner/group.
 
 [CVE-2021-25741]: https://github.com/kubernetes/kubernetes/issues/104980
 
+## Integration with Pod security admission checks
+
+{{< feature-state state="alpha" for_k8s_version="v1.29" >}}
+
+For Linux Pods that enable user namespaces, Kubernetes relaxes the application of
+[Pod Security Standards](/docs/concepts/security/pod-security-standards) in a controlled way.
+This behavior can be controlled by the [feature
+gate](/docs/reference/command-line-tools-reference/feature-gates/)
+`UserNamespacesPodSecurityStandards`, which allows an early opt-in for end
+users. Admins have to ensure that user namespaces are enabled by all nodes
+within the cluster if using the feature gate.
+
+If you enable the associated feature gate and create a Pod that uses user
+namespaces, the following fields won't be constrained even in contexts that enforce the
+_Baseline_ or _Restricted_ pod security standard. This behavior does not
+present a security concern because `root` inside a Pod with user namespaces
+actually refers to the user inside the container, that is never mapped to a
+privileged user on the host. Here's the list of fields that are **not** checks for Pods in those
+circumstances:
+
+- `spec.securityContext.runAsNonRoot`
+- `spec.containers[*].securityContext.runAsNonRoot`
+- `spec.initContainers[*].securityContext.runAsNonRoot`
+- `spec.ephemeralContainers[*].securityContext.runAsNonRoot`
+- `spec.securityContext.runAsUser`
+- `spec.containers[*].securityContext.runAsUser`
+- `spec.initContainers[*].securityContext.runAsUser`
+- `spec.ephemeralContainers[*].securityContext.runAsUser`
+
 ## Limitations
 
 When using a user namespace for the pod, it is disallowed to use other host

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

@@ -212,6 +212,7 @@ For a reference to old feature gates that are removed, please refer to
 | `TopologyManagerPolicyOptions` | `true` | Beta | 1.28 | |
 | `TranslateStreamCloseWebsocketRequests` | `false` | Alpha | 1.29 | |
 | `UnknownVersionInteroperabilityProxy` | `false` | Alpha | 1.28 | |
+| `UserNamespacesPodSecurityStandards` | `false` | Alpha | 1.29 | |
 | `UserNamespacesSupport` | `false` | Alpha | 1.28 | |
 | `ValidatingAdmissionPolicy` | `false` | Alpha | 1.26 | 1.27 |
 | `ValidatingAdmissionPolicy` | `false` | Beta | 1.28 | |
@@ -803,6 +804,10 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `UnknownVersionInteroperabilityProxy`: Proxy resource requests to the correct peer kube-apiserver when
   multiple kube-apiservers exist at varied versions.
   See [Mixed version proxy](/docs/concepts/architecture/mixed-version-proxy/) for more information.
+- `UserNamespacesPodSecurityStandards`: Enable Pod Security Standards policies relaxation for pods
+  that run with namespaces. You must set the value of this feature gate consistently across all nodes in
+  your cluster, and you must also enable `UserNamespacesSupport` to use this feature.
+  See [User Namespaces](/docs/concepts/workloads/pods/user-namespaces/#integration-with-pod-security-standards) for more details.
 - `UserNamespacesSupport`: Enable user namespace support for Pods.
   Before Kubernetes v1.28, this feature gate was named `UserNamespacesStatelessPodsSupport`.
 - `ValidatingAdmissionPolicy`: Enable [ValidatingAdmissionPolicy](/docs/reference/access-authn-authz/validating-admission-policy/)