Join our Newsletter — 33% off our NHI Course
Home› Guides› Kubernetes User Namespaces Guide: Running Pods With Remapped…
Guide Cloud Security

Kubernetes User Namespaces Guide: Running Pods With Remapped UIDs After 1.36 GA

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, under the editorial direction of Lalit Choda Updated 19 November 2026 12 min read
On this page

Kubernetes user namespaces let a pod run processes as root inside its containers while those same processes are an unprivileged user on the node, which turns many container breakouts from a node takeover into a contained failure. The feature became stable in Kubernetes v1.36 after first appearing in v1.28, and it is now locked on: the UserNamespacesSupport feature gate is ignored if you set it. What remains is a per-pod choice, made with one field, hostUsers: false. This guide explains what that field changes, what nodes and runtimes need, how it interacts with Pod Security Standards, how to verify it, and how to roll it out across a cluster.

The kernel mechanics of namespaces and cgroups are covered in the Linux Namespaces and cgroups Security Guide. This page stays on the Kubernetes feature and its operation. Facts here come from the Kubernetes documentation pages on user namespaces and using a user namespace with a pod, read in November 2026.

Key takeaways

  • Set spec.hostUsers: false on a pod to give it its own user namespace. The kubelet picks host UIDs and GIDs for each pod and guarantees no two pods on a node share a mapping.
  • Nodes need Linux kernel 6.3 or later, filesystems that support idmap mounts, runc 1.2+ or crun 1.9+, and containerd 2.0+ or CRI-O 1.25+.
  • Capabilities granted to the pod only apply inside its user namespace. CAP_SYS_MODULE has no effect, and CAP_SYS_ADMIN is limited to the pod's namespace.
  • User namespace pods cannot use hostNetwork, hostIPC, hostPID, raw block volumeDevices or NFS volumes.
  • Pod Security Standards stop checking runAsNonRoot and runAsUser for hostUsers: false pods, which makes it possible to run root-expecting images under the Restricted profile.
  • User namespaces reduce the impact of a breakout. They do not remove the need for least privilege on the pod's service account token, which is still a credential an attacker can use against the API server.

What user namespaces change in a pod

Without a user namespace, UID 0 in a container is UID 0 on the node. The container runtime narrows what that root user can do through capabilities, seccomp and other controls, but if a vulnerability lets the process escape its mount or process isolation, it arrives on the node as root. The Kubernetes documentation states this directly: without a user namespace, a container breakout running as root gives root on the node, and granted capabilities also apply on the host. MITRE ATT&CK tracks this outcome as Escape to Host (T1611).

With hostUsers: false, the container's UIDs are mapped to a separate range on the host. By default, the pod sees UIDs and GIDs 0 to 65535, and the kubelet maps them to host IDs above that range, so they do not overlap with real host users. Root in the container becomes a high, unprivileged UID on the host. Files outside the mapped range appear as the overflow ID, usually 65534, and cannot be modified even by that user.

The documentation notes that several HIGH or CRITICAL vulnerabilities were not exploitable when user namespaces were active, and expects future ones to be mitigated too. It cites CVE-2021-25741, where a pod could potentially read arbitrary host files, as a case that non-overlapping IDs limit.

Capabilities inside a user namespace

Capabilities still exist, but they are scoped to the namespace. The documentation gives two examples: CAP_SYS_MODULE has no effect, so the pod cannot load kernel modules, and CAP_SYS_ADMIN is limited to the pod's own namespace. This matters for workloads that need some privilege to work, such as build tools or software that manipulates mounts inside the container. Those workloads can get what they need inside the pod without granting the same power over the node.

What the security context fields now mean

runAsUser, runAsGroup, fsGroup and similar fields refer to the container user, not the host UID. Volume file ownership is unchanged, so pods with and without user namespaces can share volumes as long as their container IDs match. That includes hostPath if the pod is allowed to use it, which is a reminder that a hostPath mount still deserves the same scrutiny as before.

Node and runtime requirements

User namespaces are a Linux feature, and the documented requirements are specific:

ComponentDocumented requirement
KernelLinux 6.3 or later (tmpfs supports idmap mounts from 6.3)
FilesystemsThe filesystem under /var/lib/kubelet/pods/ and every filesystem used by pod volumes must support idmap mounts. On Linux 6.3 that list includes btrfs, ext4, xfs, fat, tmpfs and overlayfs.
OCI runtimerunc 1.2 or later, or crun 1.9 or later (1.13 or later recommended)
CRI runtimecontainerd 2.0 or later, or CRI-O 1.25 or later. Support in cri-dockerd is tracked upstream and not yet available.

NFS volumes cannot be used in user namespace pods because the Linux NFS client does not yet support idmap mounts. If a node or volume does not meet the requirements, pod start fails with an event similar to failed to set MOUNT_ATTR_IDMAP ... invalid argument (maybe the filesystem used doesn't support idmap mounts on this kernel?). Treat that message as a signal to check the node image and storage class rather than to remove hostUsers: false.

In mixed fleets, label nodes that meet the requirements and use node affinity or a dedicated node pool so that user namespace pods land only where they can run. The task page recommends scheduling pods to suitable nodes when only some nodes support the feature.

Enabling user namespaces for a pod

The documented example is short:

apiVersion: v1
kind: Pod
metadata:
  name: userns
spec:
  hostUsers: false
  containers:
  - name: shell
    command: ["sleep", "infinity"]
    image: debian

For Deployments, StatefulSets, Jobs and DaemonSets, set the same field in the pod template. Setting hostUsers: false disallows hostNetwork: true, hostIPC: true and hostPID: true, and no container, init container or ephemeral container may use volumeDevices. Workloads that need those settings are, by definition, node-level agents, and they should stay in a separate, tightly governed class of workloads.

Verifying that a pod uses a user namespace

The Kubernetes task page gives a simple check. Exec into the pod and run:

  • readlink /proc/self/ns/user, which prints the user namespace identifier.
  • cat /proc/self/uid_map, which prints the mapping. The example output is 0 833617920 65536: container UID 0 maps to a high host UID, for a range of 65536 IDs.

Run the same two commands in a shell on the node. The readlink output should differ between the container and the host, and the last number in the container's uid_map should be 65536 while the host's is larger. If the kubelet itself runs inside a user namespace, compare against the kubelet process with readlink /proc/$pid/ns/user instead.

For fleet-level visibility, the kubelet exposes two counters: started_user_namespaced_pods_total for creation attempts and started_user_namespaced_pods_errors_total for errors. A rising error count after a node image change is an early warning that idmap support has regressed somewhere.

Pod Security Standards and admission policy

User namespaces change how the Pod Security Standards treat some fields. For pods with hostUsers: false, the documentation states that runAsNonRoot and runAsUser are not checked, even under Baseline or Restricted, across pod, container, init container and ephemeral container security contexts. Under Baseline only, procMount validation is also relaxed. Under Restricted, the pod must still use the default or empty ProcMount.

The practical effect is that images which insist on running as root, and which were previously blocked by Restricted, can now be admitted under Restricted when they run in a user namespace. That is a reasonable trade, because root in the container is no longer root on the node. It also means the absence of a runAsNonRoot check is no longer a sign of a weak policy for those pods.

Pod Security Admission does not require hostUsers: false. If you want it enforced for a namespace, add a validating admission policy or a policy engine rule that rejects pods where hostUsers is missing or true, with an explicit exemption list for node agents. Teams still migrating from the removed PodSecurityPolicy should read PodSecurityPolicy to Pod Security Admission first, so that user namespace enforcement is layered on a working baseline.

Kubelet ID ranges and capacity

Each pod gets 65536 IDs by default. From v1.33 the kubelet configuration accepts a userNamespaces.idsPerPod value, a multiple of 65536, for workloads that need more IDs. It applies only to containers created after the kubelet starts with the new configuration.

Operators can also give the kubelet an explicit host ID range. The documented requirements are a user named exactly kubelet, the getsubids binary from shadow-utils in the kubelet's PATH, and one line each in /etc/subuid and /etc/subgid. The starting ID must be a multiple of 65536 and at least 65536; the count must be a multiple of 65536 and at least 65536 times the node's maximum pods; and the UID and GID ranges must be the same and must not overlap with other assignments. The documented example is kubelet:65536:7208960, which is 110 pods times 65536.

Changing the range on a live node needs care. Drain the node first if any user namespace pods are running, then restart the kubelet. The documentation warns that drain does not evict DaemonSet pods or pods that tolerate the unschedulable taint, and that the kubelet fails to start if it cannot honour the new range for existing pods. Build this into node image changes rather than doing it by hand.

Keep subordinate ID ranges for other local users clear of the kubelet range. Overlap would undo the guarantee that pod IDs never collide with host IDs.

What user namespaces do not fix

User namespaces are a strong node-protection control, but they sit alongside others rather than replacing them:

  • Service account tokens. A compromised pod still holds whatever Kubernetes API permissions its service account has. Breaking out to the node is harder, but moving laterally through the API is unchanged. Disable token automounting where pods do not call the API, and scope RBAC tightly. The Kubernetes Security Guide covers service account design.
  • Cloud credentials. Workload identity tokens and mounted cloud secrets are equally available to an attacker inside the pod. Least privilege on those identities still decides the blast radius.
  • Kernel attack surface. A user namespace gives the pod the ability to use some kernel features that were previously limited to root, inside its namespace. Keep seccomp profiles on, prefer the RuntimeDefault profile at minimum, and patch kernels quickly.
  • Shared volumes and hostPath. Ownership on volumes is unchanged. A hostPath mount of a sensitive node directory is still dangerous.
  • Node agents. Pods that need host networking or host PID cannot use the feature at all.

Rollout plan for a cluster

  1. Check the platform. Confirm control plane and kubelet versions, node kernel versions, runtime versions and the filesystems backing the kubelet directory and storage classes. Managed Kubernetes providers publish node image versions; confirm their kernel and runtime against the table above.
  2. Classify workloads. Mark node agents that need host namespaces as exempt. Mark workloads using NFS or raw block volumes as blocked until storage changes. Everything else is a candidate.
  3. Pilot. Start with stateless services in a non-production namespace. Verify with the readlink and uid_map checks and watch the kubelet error counter.
  4. Test file ownership. Applications that write to persistent volumes, or that rely on files owned by specific UIDs, need a test with real data to confirm the container IDs line up.
  5. Enforce by namespace. Add an admission rule requiring hostUsers: false in namespaces that have moved, and widen it over time.
  6. Revisit privilege. For workloads that were granted capabilities to work around root restrictions, check whether the namespace-scoped capability is now enough, and remove any remaining privileged settings.

Common failure patterns

  • Old node images. A kernel below 6.3 or a runtime below the documented versions causes pod start failures that teams misread as application bugs.
  • NFS-backed storage. Workloads on NFS volumes cannot use user namespaces, and this is often discovered only at deploy time.
  • Treating the feature as global. GA means the support is always on, not that every pod is protected. Without hostUsers: false, a pod still shares the host's user namespace.
  • Removing other controls. Teams relax seccomp, capabilities or RBAC on the assumption that user namespaces cover everything.
  • Subordinate ID overlap. Manually configured /etc/subuid ranges that overlap with other users undermine the separation.
  • Kubelet range changes without draining. The kubelet fails to start, and DaemonSet pods are not moved by drain.
  • Admission gaps. Relying on Pod Security Admission alone, which does not require the field, leaves new workloads unprotected by default.

Practitioner checklist

  • Confirm nodes run Linux 6.3 or later with idmap-capable filesystems for the kubelet directory and all pod volumes.
  • Confirm runc 1.2+ or crun 1.9+ and containerd 2.0+ or CRI-O 1.25+ on every node pool that will run user namespace pods.
  • Set hostUsers: false in pod templates for all workloads that do not need host namespaces, NFS or raw block devices.
  • Verify with readlink /proc/self/ns/user and cat /proc/self/uid_map, and monitor started_user_namespaced_pods_errors_total.
  • Enforce hostUsers: false through admission policy per namespace, with a documented exemption list.
  • Keep Pod Security Standards, seccomp and capability limits in place, and remove privileged settings that are no longer needed.
  • Scope service account RBAC and disable token automounting for pods that do not call the API.
  • Drain nodes before changing kubelet ID ranges and keep subordinate ID ranges non-overlapping.

Standards and references

Related NHI Mgmt Group resources: Linux Namespaces and cgroups Security Guide · Kubernetes Security Guide · PodSecurityPolicy to Pod Security Admission · Top 10 Kubernetes Security Risks

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick both boxes to continue.