How to Implement User Namespaces in Kubernetes for Enhanced Container Security

Introduction

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 rootless isolation while still granting inside-the-container administrative capabilities like CAP_NET_ADMIN. 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.

The key enabler behind this feature is ID-mapped mounts, a kernel mechanism (Linux 5.12+) that performs transparent UID/GID remapping at mount time—no expensive chown operations needed. This guide walks you through everything you need to know to start using user namespaces in your Kubernetes workloads.

What You Need

• A Kubernetes cluster running v1.36 or later on Linux nodes.
• Linux kernel 5.12+ (for ID-mapped mounts) on all nodes where user namespace pods will run.
• A container runtime that supports user namespaces (e.g., containerd v1.7+ or CRI-O v1.29+).
• kubectl installed and configured to access your cluster.
• Basic familiarity with Pod specs and securityContext.

Step-by-Step Guide

Step 1: Verify Cluster Compatibility

First, confirm your cluster meets the prerequisites:

1. Check the Kubernetes version: kubectl version --short. The server version must be at least 1.36.
2. Ensure your nodes run a Linux kernel 5.12 or newer: kubectl get nodes -o json | jq '.items[].status.nodeInfo.kernelVersion'. Output should be like 5.15.x or higher.
3. Verify your container runtime supports user namespaces. For containerd, run crictl info and look for userNamespaces: true. If not present, upgrade the runtime.

Step 2: Create a Pod with hostUsers: false

The simplest way to enable user namespaces is to set hostUsers: false in the Pod spec. This tells Kubernetes to run the pod’s containers in a dedicated user namespace, isolated from the host.

apiVersion: v1
kind: Pod
metadata:
  name: isolated-workload
spec:
  hostUsers: false
  containers:
    - name: app
      image: fedora:42
      securityContext:
        runAsUser: 0

Note: Setting runAsUser: 0 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.

Step 3: (Optional) Configure Privileged Capabilities Inside the Namespace

With hostUsers: false, capabilities such as CAP_NET_ADMIN are namespaced. 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.

securityContext:
  capabilities:
    add: ["NET_ADMIN"]

This pattern is a game-changer for network-heavy applications or testing scenarios where full host privileges were previously required.

Step 4: Mount Volumes – Leverage ID‑mapped Mounts

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 chown is performed, making volume mounts instant even for large datasets.

volumes:
  - name: data
    persistentVolumeClaim:
      claimName: my-pvc

The translation is transparent—just mount as usual. This eliminates the startup performance penalty that earlier implementations suffered.

Step 5: Verify the User Namespace Isolation

After the pod starts, verify isolation:

1. Exec into the pod: kubectl exec -it isolated-workload -- bash
2. Check the UID mapping: cat /proc/self/uid_map. You should see a mapping like 0 100000 65536, meaning container UID 0 maps to host UID 100000.
3. Attempt to escape: run nsenter --target 1 --mount --uts --ipc --pid /bin/bash – this should fail because the container’s namespace is fully isolated.

Step 6: Test with Privileged Workloads (Optional)

To demonstrate that privileged capabilities are confined, try adding CAP_SYS_ADMIN and attempting host-level actions:

# 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

If the kernel allows the operation but only within the container’s own namespace, the feature is working correctly.

Step 7: Monitor Performance

User namespaces add minimal overhead, but you can monitor CPU and memory with kubectl top pod. ID‑mapped mounts are O(1), so large volumes should mount instantly. If you see slow startup times, check kernel version and runtime support.

Tips for Success

• Start small. Test user namespaces with stateless pods first before moving to stateful workloads.
• Verify runtime support. Not all container runtimes enable user namespaces by default. For containerd, you may need to add "userNamespaces": { "enabled": true } to the configuration file.
• Combine with other security features. User namespaces work well with seccomp, AppArmor, and Pod Security Standards. They add an extra layer—not a replacement.
• Be aware of volume limitations. Some CSI drivers or NFS mounts might not support ID‑mapped mounts. Test with your storage provider.
• Monitor for regressions. While GA, user namespaces are still relatively new. Keep an eye on Kubernetes changelogs and runtime updates.
• Use hostUsers: false as a default. For new deployments, enabling user namespaces by default reduces the attack surface significantly.

For more detailed information, refer to the testing section above or the official Kubernetes documentation.