Merge pull request #46218 from rata/rata/userns-1.29-backports

[release-1.29]: Fix userns example and add OCI runtime requirements

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

@@ -46,7 +46,26 @@ tmpfs, Secrets use a tmpfs, etc.)
 Some popular filesystems that support idmap mounts in Linux 6.3 are: btrfs,
 ext4, xfs, fat, tmpfs, overlayfs.
 
-In addition, support is needed in the 
+In addition, the container runtime and its underlying OCI runtime must support
+user namespaces. The following OCI runtimes offer support:
+
+* [crun](https://github.com/containers/crun) version 1.9 or greater (it's recommend version 1.13+).
+
+<!-- ideally, update this if a newer minor release of runc comes out, whether or not it includes the idmap support -->
+{{< note >}}
+Many OCI runtimes do not include the support needed for using user namespaces in
+Linux pods. If you use a managed Kubernetes, or have downloaded it from packages
+and set it up, it's likely that nodes in your cluster use a runtime that doesn't
+include this support. For example, the most widely used OCI runtime is `runc`,
+and version `1.1.z` of runc doesn't support all the features needed by the
+Kubernetes implementation of user namespaces.
+
+If there is a newer release of runc than 1.1 available for use, check its
+documentation and release notes for compatibility (look for idmap mounts support
+in particular, because that is the missing feature).
+{{< /note >}}
+
+To use user namespaces with Kubernetes, you also need to use a CRI
 {{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}
 to use this feature with Kubernetes pods:
 

content/en/docs/tasks/configure-pod-container/user-namespaces.md

@@ -82,27 +82,42 @@ to `false`. For example:
    kubectl attach -it userns bash
    ```
 
-And run the command. The output is similar to this:
+Run this command:
 
-```none
+```shell
 readlink /proc/self/ns/user
-user:[4026531837]
-cat /proc/self/uid_map
-0          0 4294967295
 ```
 
-Then, open a shell in the host and run the same command.
+The output is similar to:
 
-The output must be different. This means the host and the pod are using a
-different user namespace. When user namespaces are not enabled, the host and the
-pod use the same user namespace.
+```shell
+user:[4026531837]
+```
+
+Also run:
+
+```shell
+cat /proc/self/uid_map
+```
+
+The output is similar to:
+```shell
+0  833617920      65536
+```
+
+Then, open a shell in the host and run the same commands.
+
+The `readlink` command shows the user namespace the process is running in. It
+should be different when it is run on the host and inside the container.
+
+The last number of the `uid_map` file inside the container must be 65536, on the
+host it must be a bigger number.
 
 If you are running the kubelet inside a user namespace, you need to compare the
 output from running the command in the pod to the output of running in the host:
 
-```none
+```shell
 readlink /proc/$pid/ns/user
-user:[4026534732]
 ```
 
 replacing `$pid` with the kubelet PID.