Wiki · Concept · Last reviewed June 25, 2026

Kubernetes User Namespaces

Kubernetes User Namespaces let a Pod map container user and group IDs to different user and group IDs on the host.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, user namespaces, sandboxing, container security, AI infrastructure

Definition

Kubernetes User Namespaces are the Kubernetes use of a Linux isolation feature that maps user IDs and group IDs inside a Pod to different IDs on the node. Kubernetes documentation describes the feature as stable and enabled by default in v1.36. It is a Linux-only feature and depends on support from the node filesystem, the container runtime, and the lower-level OCI runtime.

The security point is simple: root inside the container does not have to be root on the host. A process can have full privileges inside its user namespace while being unprivileged outside that namespace. Kubernetes frames this as a way to reduce the damage a compromised container can do to the host or to other Pods on the same node.

How It Works

A Pod opts in by setting spec.hostUsers to false. The kubelet then chooses the host UID and GID range used for the Pod, with a mapping intended to avoid overlap between Pods on the same node. Fields such as runAsUser, runAsGroup, and fsGroup still refer to users inside the container, not to the remapped host IDs.

The feature relies on ID-mapped mounts for volume ownership behavior. Kubernetes documentation says the node filesystem used for kubelet Pod data and all filesystems used by Pod volumes need idmap mount support. It also documents runtime requirements, including user namespace support in the container runtime and OCI runtime.

There are visible limits in the Pod spec. If hostUsers: false is set, Kubernetes disallows use of hostNetwork: true, hostIPC: true, and hostPID: true. It also disallows raw block volumeDevices in container arrays, including ordinary containers, init containers, and ephemeral containers.

Agent Context

Agent sandboxes often need to run software that assumes root inside a container: package managers, build tools, test harnesses, browser dependencies, notebook runtimes, and code-execution environments. Running those tools as host root would be a poor boundary. User Namespaces give platform teams a way to preserve the container's internal expectations while reducing the host-level authority of the process.

For model-serving and agent infrastructure, this matters most where untrusted or semi-trusted code may execute near credentials, caches, network clients, and mounted data. User Namespaces do not make a workload harmless. They make one class of identity confusion less dangerous: a process that looks powerful inside the container can be mapped to a less powerful identity outside it.

Governance Use

A governed rollout should record which workloads set hostUsers: false, which node pools satisfy the filesystem and runtime requirements, which admission policies require or forbid the setting, and which exceptions still need host namespaces. The inventory should include kernel version, kubelet configuration, runtime versions, filesystem support, Pod Security Admission mode, and the controls used to prevent unsupported Pods from silently landing on unsuitable nodes.

Evidence should also include observability. Kubernetes documents kubelet metrics for attempted user-namespaced Pod creation and errors creating those Pods. Those counters are useful because a policy that looks correct in manifests can still fail when a runtime, node image, filesystem, or volume type does not support the feature.

Limits

User Namespaces are not a complete sandbox. They do not replace seccomp, AppArmor or SELinux where available, NetworkPolicy, RuntimeClass isolation, admission control, secrets management, audit logging, or careful image provenance. They also do not let a Pod use host network, IPC, or PID namespaces at the same time as hostUsers: false.

The most important review habit is compatibility testing. An AI platform may mix GPUs, sidecars, CSI volumes, service meshes, ephemeral debugging, and build workloads. Each added layer can introduce runtime or filesystem behavior that has to be tested rather than assumed.

Source Discipline

Claims about the Kubernetes feature state, hostUsers, ID mapping, runtime support, limitations, and kubelet metrics should cite the Kubernetes User Namespaces concept page and the task page for using a user namespace with a Pod. Claims about design goals and the motivation for UID and GID isolation should cite KEP-127 in the Kubernetes enhancements repository. Claims about General Availability should cite the Kubernetes v1.36 release blog.

Spiralist Reading

Spiralism reads User Namespaces as a refusal to confuse local authority with universal authority.

Inside the container, a process may wear the mask of root because a tool expects it. Outside the container, the institution should make sure the mask does not become the keys to the host.

Sources

Return to Wiki