How to Enable User Namespaces in Kubernetes v1.36 for Enhanced Container Security

Introduction

After years of development, Kubernetes v1.36 has finally made User Namespaces generally available (GA) on Linux. This feature allows you to run containers as root without giving them actual root privileges on the host. Instead, the container’s root user is mapped to a non-privileged user on the host, drastically reducing the blast radius of a container breakout. This guide walks you through enabling and using User Namespaces in your Kubernetes workloads, from understanding the concept to verifying the setup.

How to Enable User Namespaces in Kubernetes v1.36 for Enhanced Container Security

What You Need

A Kubernetes cluster running v1.36 or later (Linux nodes only)
kubectl configured to interact with the cluster
Basic knowledge of Pod specifications and security contexts
Node kernel version Linux 5.12+ (for ID‑mapped mounts support)
Container runtime that supports user namespaces (e.g., containerd 1.6+, CRI‑O 1.24+)

Step-by-Step Guide

Step 1: Verify Your Cluster Version

Before you begin, ensure your cluster is running Kubernetes v1.36 or newer. Check with:

kubectl version --short

If you see a server version less than 1.36, upgrade your cluster first. User Namespaces are not available in earlier versions.

Step 2: Understand the Key Setting – hostUsers: false

The core of User Namespaces support is the hostUsers field in the Pod spec. Setting hostUsers: false tells Kubernetes to isolate the Pod’s user namespace from the host. This means any UID inside the container (including UID 0 “root”) is remapped to a non‑privileged UID on the host. The container can still run as root internally, but the kernel sees a different, unprivileged user. This is different from running a container with a non‑root user – here the container can have all the privileges it needs, but they are namespaced.

Step 3: Create a Pod with User Namespaces Enabled

Write a Pod manifest that includes hostUsers: false. For example:

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

Notice that runAsUser: 0 is still allowed. Inside the container, the process runs as root, but thanks to the user namespace, that root identity is mapped to a high, unprivileged UID on the host. You do not need to change your container images – they work as before.

Step 4: Apply the Pod and Verify Isolation

Deploy the Pod with:

kubectl apply -f pod.yaml

Check the Pod’s events and status:

kubectl describe pod isolated-workload

You should see the user namespace being enabled automatically. To confirm isolation, you can exec into the container and check the UID mapping:

kubectl exec -it isolated-workload -- cat /proc/self/uid_map

This will show a mapping like 0 1000000 65536, meaning the container’s UID 0 corresponds to UID 1000000 on the host.

Step 5: Work with Volumes – ID‑mapped Mounts at Work

A critical enabler for User Namespaces is ID‑mapped mounts, introduced in Linux 5.12. When you attach a PersistentVolume or a hostPath volume to a Pod with hostUsers: false, the kernel automatically remaps file ownership at mount time. For example, if the volume has files owned by UID 1000000 on disk, the container sees them as owned by UID 0. No chown is needed, even for large volumes. This is an O(1) operation and does not affect start‑up performance.

To test, attach a volume to your Pod and check file permissions inside the container versus on the host. Inside the container, files will appear owned by root; on the host, they remain with the high UID.

Step 6: Use Namespaced Capabilities (e.g., CAP_NET_ADMIN)

One of the most powerful benefits of User Namespaces is that capabilities become namespaced. For example, granting CAP_NET_ADMIN inside a Pod with hostUsers: false gives the container control over its own network namespace (e.g., creating virtual interfaces) without affecting the host network. This was previously only possible by running a fully privileged container. Add the capability in the security context:

securityContext:
  capabilities:
    add: ["NET_ADMIN"]

Now the container can run network‑related commands that would normally require root, but the host remains secure. Test this by execing into the container and running ip link add dummy0 type dummy – it should succeed.

Tips and Best Practices

Always test with non‑production workloads first. While the feature is GA, ensure your applications handle the remapped UIDs correctly, especially when reading file ownership from volumes.
Combine with Pod Security Standards. User Namespaces complement, but do not replace, other security measures like seccomp, AppArmor, and network policies.
Monitor kernel version. ID‑mapped mounts require Linux kernel 5.12+. Older kernels will fall back to slow recursive chown, degrading performance. Verify your nodes’ kernel versions.
Use hostUsers: false as a default. Consider mutating webhooks or Pod security admission to enforce it for all workloads. This drastically reduces the risk of breakout exploits.
Check runtime support. Not all container runtimes support user namespaces yet. If you encounter errors, upgrade your runtime to a version that explicitly supports this feature (e.g., containerd 1.6+, CRI‑O 1.24+).
Remember: Linux only. This feature does not apply to Windows nodes. Ensure your Pods are scheduled only on Linux nodes when using hostUsers: false.

By following these steps, you can leverage Kubernetes v1.36’s User Namespaces to run containers with root privileges internally while keeping the host safe—a long‑awaited milestone for secure, rootless container orchestration.