How to Implement User Namespaces in Kubernetes for Enhanced Container Security

By ✦ min read

<h2>Introduction</h2> <p>After years of development, Kubernetes v1.36 finally brings User Namespaces to General Availability (GA) for Linux nodes. This feature allows you to run containers with <strong>rootless isolation</strong> while still granting inside-the-container administrative capabilities like <code>CAP_NET_ADMIN</code>. User namespaces solve a critical security problem: processes running as UID 0 inside a container are no longer seen as root on the host. Instead, they operate within a remapped user namespace, so even if an attacker escapes the container, they have no host privileges.</p><figure style="margin:20px 0"><img src="https://picsum.photos/seed/2559617446/800/450" alt="How to Implement User Namespaces in Kubernetes for Enhanced Container Security" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px"></figcaption></figure> <p>The key enabler behind this feature is <em>ID-mapped mounts</em>, a kernel mechanism (Linux 5.12+) that performs transparent UID/GID remapping at mount time—no expensive <code>chown</code> operations needed. This guide walks you through everything you need to know to start using user namespaces in your Kubernetes workloads.</p> <h2>What You Need</h2> <ul> <li>A Kubernetes cluster running <strong>v1.36</strong> or later on Linux nodes.</li> <li>Linux kernel <strong>5.12+</strong> (for ID-mapped mounts) on all nodes where user namespace pods will run.</li> <li>A container runtime that supports user namespaces (e.g., <strong>containerd</strong> v1.7+ or <strong>CRI-O</strong> v1.29+).</li> <li><code>kubectl</code> installed and configured to access your cluster.</li> <li>Basic familiarity with Pod specs and <code>securityContext</code>.</li> </ul> <h2>Step-by-Step Guide</h2> <h3>Step 1: Verify Cluster Compatibility</h3> <p>First, confirm your cluster meets the prerequisites:</p> <ol> <li>Check the Kubernetes version: <code>kubectl version --short</code>. The server version must be at least 1.36.</li> <li>Ensure your nodes run a Linux kernel 5.12 or newer: <code>kubectl get nodes -o json | jq '.items[].status.nodeInfo.kernelVersion'</code>. Output should be like <code>5.15.x</code> or higher.</li> <li>Verify your container runtime supports user namespaces. For containerd, run <code>crictl info</code> and look for <code>userNamespaces: true</code>. If not present, upgrade the runtime.</li> </ol> <h3>Step 2: Create a Pod with <code>hostUsers: false</code></h3> <p>The simplest way to enable user namespaces is to set <code>hostUsers: false</code> in the Pod spec. This tells Kubernetes to run the pod’s containers in a dedicated user namespace, isolated from the host.</p> <pre><code>apiVersion: v1 kind: Pod metadata: name: isolated-workload spec: hostUsers: false containers: - name: app image: fedora:42 securityContext: runAsUser: 0 </code></pre> <p>Note: Setting <code>runAsUser: 0</code> inside the container is fine—it refers to the container’s own UID 0, which is remapped by the kernel to a high, unprivileged host UID.</p> <h3>Step 3: (Optional) Configure Privileged Capabilities Inside the Namespace</h3> <p>With <code>hostUsers: false</code>, capabilities such as <code>CAP_NET_ADMIN</code> are <strong>namespaced</strong>. They grant full administrative power over the container’s network stack but have no effect on the host. This allows you to run workloads that need net admin (e.g., tuning network interfaces) without giving real root to the container.</p> <pre><code>securityContext: capabilities: add: ["NET_ADMIN"] </code></pre> <p>This pattern is a game-changer for network-heavy applications or testing scenarios where full host privileges were previously required.</p> <h3>Step 4: Mount Volumes – Leverage ID‑mapped Mounts</h3> <p>When you attach a volume to a user‑namespace pod, the kernel automatically remaps UIDs at mount time. The container sees files owned by UID 0, while on disk the ownership remains unchanged. No recursive <code>chown</code> is performed, making volume mounts instant even for large datasets.</p> <pre><code>volumes: - name: data persistentVolumeClaim: claimName: my-pvc </code></pre> <p>The translation is transparent—just mount as usual. This eliminates the startup performance penalty that earlier implementations suffered.</p> <h3>Step 5: Verify the User Namespace Isolation</h3> <p>After the pod starts, verify isolation:</p> <ol> <li>Exec into the pod: <code>kubectl exec -it isolated-workload -- bash</code></li> <li>Check the UID mapping: <code>cat /proc/self/uid_map</code>. You should see a mapping like <code>0 100000 65536</code>, meaning container UID 0 maps to host UID 100000.</li> <li>Attempt to escape: run <code>nsenter --target 1 --mount --uts --ipc --pid /bin/bash</code> – this should fail because the container’s namespace is fully isolated.</li> </ol> <h3>Step 6: Test with Privileged Workloads (Optional)</h3> <p>To demonstrate that privileged capabilities are confined, try adding <code>CAP_SYS_ADMIN</code> and attempting host-level actions:</p> <pre><code># Inside the pod with added CAP_SYS_ADMIN mount -t tmpfs tmpfs /mnt # works for container’s mount namespace only cat /proc/1/environ # should be empty or not accessible </code></pre> <p>If the kernel allows the operation but only within the container’s own namespace, the feature is working correctly.</p> <h3>Step 7: Monitor Performance</h3> <p>User namespaces add minimal overhead, but you can monitor CPU and memory with <code>kubectl top pod</code>. ID‑mapped mounts are O(1), so large volumes should mount instantly. If you see slow startup times, check kernel version and runtime support.</p> <h2>Tips for Success</h2> <ul> <li><strong>Start small.</strong> Test user namespaces with stateless pods first before moving to stateful workloads.</li> <li><strong>Verify runtime support.</strong> Not all container runtimes enable user namespaces by default. For containerd, you may need to add <code>"userNamespaces": { "enabled": true }</code> to the configuration file.</li> <li><strong>Combine with other security features.</strong> User namespaces work well with seccomp, AppArmor, and Pod Security Standards. They add an extra layer—not a replacement.</li> <li><strong>Be aware of volume limitations.</strong> Some CSI drivers or NFS mounts might not support ID‑mapped mounts. Test with your storage provider.</li> <li><strong>Monitor for regressions.</strong> While GA, user namespaces are still relatively new. Keep an eye on Kubernetes changelogs and runtime updates.</li> <li><strong>Use <code>hostUsers: false</code> as a default.</strong> For new deployments, enabling user namespaces by default reduces the attack surface significantly.</li> </ul> <p>For more detailed information, refer to the <a href="#step-6">testing section</a> above or the <a href="https://kubernetes.io/docs/concepts/security/user-namespaces/" target="_blank" rel="noopener noreferrer">official Kubernetes documentation</a>.</p>