What Is a Pod Sandbox? Pause Containers, CRI, and the Node Network Chain
On a Kubernetes node, setting up Pod networking is typically summarized in three steps: the kubelet asks the container runtime to create a Pod sandbox via the CRI (Container Runtime Interface); the runtime invokes a CNI (Container Network Interface) plugin during sandbox creation; and CNI provisions network interfaces, allocates an IP address, and attaches the sandbox to the Pod network.
While this invocation sequence seems straightforward, the term Pod sandbox is often a major source of confusion. Across documentation and daily discussions, it wears multiple hats: an abstract interface concept, a gRPC API object, and the mysterious pause container running on your node.
PodSandbox Is First and Foremost a CRI API Specification
Architecturally, the sandbox begins as an interface concept, materializes as a gRPC API contract, and is only then implemented by underlying container runtimes.
The original 2016 CRI announcement laid out the baseline definition:
A Pod is composed of a group of application containers in an isolated environment with resource constraints. In CRI, this environment is called PodSandbox.
In other words, the CRI specification formally designates an “isolated environment with resource constraints” as a Pod sandbox.
The CRI Protocol Buffers API is divided into two primary gRPC services: ImageService, which handles image pulling and management, and RuntimeService, which manages the full lifecycle of pods and containers—including interactive channels such as exec, attach, and port-forwarding.
Inside RuntimeService, the sandbox is a first-class citizen with its own lifecycle and a dedicated suite of RPC methods:
RunPodSandbox: “creates and starts a pod-level sandbox. Runtimes must ensure the sandbox is in the ready state on success.” On success, the runtime must guarantee that the sandbox reaches theSANDBOX_READYstate.StopPodSandbox: “stops any running process that is part of the sandbox and reclaims network resources (e.g., IP addresses) allocated to the sandbox.” It reclaims the network resources (such as IP addresses) allocated to the sandbox. This operation is idempotent.RemovePodSandbox: Removes the sandbox. If containers are still running within the sandbox, the runtime forcibly terminates and cleans them up. This call is also idempotent.PodSandboxStatusandListPodSandbox: Used by the kubelet to query and reconcile the health and state of all sandboxes on the node.
Why does the CRI API enforce a strict order of “sandbox first, containers second”? Because in the CreateContainer request structure, the very first required field is pod_sandbox_id (“ID of the PodSandbox in which the container should be created”).
This constraint reflects a concrete technical dependency: the network namespace that application container processes need to join, the pod-level cgroups they must bind to, and the Pod’s IP address must all be established during the sandbox phase before subsequent containers can start.
This ordering is also mirrored in Pod conditions. The PodReadyToStartContainers condition is defined as “the Pod sandbox has been successfully created, networking configured, storage volumes mounted…” Only when the sandbox and underlying network infrastructure are in place does the Pod reach the ready state required to host application containers.
Abstract Specifications and Underlying Entities: Deliberate Architectural Flexibility
If the sandbox is an abstract specification at the API tier, what is it under the hood—a container, a virtual machine, or something else entirely? CRI designers explicitly addressed this in their initial design post:
We intentionally leave some room for the container runtimes to interpret the PodSandbox differently based on how they operate internally. For hypervisor-based runtimes, PodSandbox might represent a virtual machine. For others, such as Docker, it might be Linux namespaces.
This design principle holds true today.
Current Kubernetes Pod lifecycle documentation still explicitly accounts for VM scenarios when describing abnormal sandbox restarts: “for container runtimes that use virtual machines for isolation, the Pod sandbox virtual machine rebooting, which then requires creating a new sandbox and fresh container network configuration.”
Equating a “Pod sandbox” with a “pause container” is therefore inaccurate. The pause container is merely how the sandbox is implemented in Linux container runtimes (such as containerd and CRI-O), not the universal definition of a sandbox.
The definition itself is an architectural slot for a “pod-level isolated environment.” Whether that slot is filled by Linux namespaces or a microVM is entirely up to the underlying runtime.
- CRI Interface: PodSandbox
-
- Linux Namespace / cgroupcontainerd / CRI-O
- Sandboxed RuntimeKata / gVisor
On Linux Nodes: Anatomy and Source Code of the Pause Container
On Linux nodes running mainstream containerd or CRI-O, the sandbox typically materializes as the pause container.
When the kubelet invokes RunPodSandbox, containerd creates a dedicated network namespace for the Pod, configures networking via CNI, and then launches a purpose-built pause container within the Pod’s cgroups and namespaces to serve as the sandbox container.
The source code for the pause container is remarkably concise, residing in the Kubernetes repository at build/pause/linux/pause.c. The core of its main function simply calls the Unix system call pause(2) to put the process to sleep until it catches a signal. Despite its minimal footprint, it carries out critical system-level responsibilities:
1. Lifecycle Anchor for Namespaces and cgroups (Core Responsibility)
In the Linux kernel, a network namespace persists as long as at least one running process resides within it.
After CNI creates and configures the Pod network, the pause container steps in and runs continuously, anchoring the network namespace in memory. Application containers created later simply join this namespace and thereby share the same network stack, IP address, and localhost environment.
2. PID 1 Surrogate and Zombie Process Reaping (Conditional)
It is common to hear people say that “the pause container does nothing.” Strictly speaking, pause is designed to sleep by default; but inspecting the source code of pause.c reveals that it registers a SIGCHLD handler:
static void sigreap(int signo) {
while (waitpid(-1, NULL, WNOHANG) > 0)
;
}
This non-blocking reaping loop only comes into play under specific circumstances. By default, containers in a Pod each get an isolated PID namespace, and the application process serves as its own PID 1.
Only when shareProcessNamespace: true is enabled in the Pod spec do all containers share a single process namespace. When that happens, pause acts as PID 1 for the entire Pod, promptly reaping orphaned zombie processes whenever it catches a SIGCHLD signal.
Timing and Evolution of the Node Networking Call Chain
Having seen how pause anchors namespaces at the Linux kernel level, let’s zoom out to the node component level to examine the complete networking call sequence driven by RunPodSandbox:
Kubelet Runtime (containerd) CNI
| | |
| 1. RunPodSandbox | |
|--------------------->| |
| | |
| |--+ 2. Create |
| | | netns |
| |<-+ |
| | |
| | 3. CNI ADD |
| |--------------->|
| | |
| | |--+ 4. Setup
| | | | veth/IP
| | |<-+
| | |
| | 5. Return IP |
| |<---------------|
| | |
| |--+ 6. Launch |
| | | pause |
| |<-+ |
| | |
| 7. SANDBOX_READY | |
|<---------------------| |
| | |
| 8. CreateContainer | |
|--------------------->| |
| | |
| |--+ 9. App |
| | | joins |
| |<-+ |
This sequence diagram illustrates three key facts:
- The kubelet requests the runtime to create a sandbox via CRI: the kubelet initiates
RunPodSandboxover gRPC and never directly interacts with underlying network devices. - The runtime invokes CNI: Prior to the removal of dockershim in Kubernetes 1.24, the kubelet invoked CNI directly using
--cni-bin-dirand--network-plugin. Since 1.24, CNI management has moved entirely into the CRI runtime. - The IP address belongs to the sandbox: After CNI creates the virtual network interface pair (veth pair) and allocates an IP address, this IP information is recorded in CRI’s
PodSandboxNetworkStatus. Application containers have no independent IP addresses; theeth0interface and IP address visible inside any container come directly from the sandbox network namespace it joined.
If a Pod sets hostNetwork: true, the runtime reuses the node’s network namespace directly. In this case, CNI is bypassed, the sandbox network status is omitted at the API level, and the Pod IP is simply the node’s IP.
NOTE
Further reading: Why Kubernetes Removed Docker
Lifecycle and Node Troubleshooting: When a Sandbox Fails
During a normal shutdown, the kubelet stops the application containers first, issues StopPodSandbox (which triggers CNI DEL to tear down networking and reclaim IP resources), and finally calls RemovePodSandbox to clean up the sandbox data structures.
Sandbox Crashes and the Recreation Mechanism
If a node reboots unexpectedly or an underlying VM sandbox crashes, the kubelet detects the failure, sets PodReadyToStartContainers to False, and launches a fresh sandbox.
Sandbox recreation means that the entire baseline environment for the Pod is reset: all existing application containers are destroyed, CNI re-executes network provisioning, and the Pod IP is typically reallocated (unless the underlying CNI plugin supports sticky or static IPs). In the CRI, the PodSandboxMetadata.attempt counter increments with every recreation.
Observability: Contrasting Perspectives Between crictl and kubectl
When troubleshooting networking or startup failures, it helps to understand the difference in perspective between crictl and kubectl:
- Node level (crictl): Sandboxes and application containers are strictly separated.
crictl podslists allPodSandboxobjects (including their status and recreationATTEMPTcount), whilecrictl psonly displays application containers (excludingpause). Operational commands are similarly split betweencrictl stopp/rmpandcrictl stop/rm. - Cluster level (kubectl):
kubectl describe podonly exposes Pod conditions and application container lists; the pause container is completely hidden from cluster-level API objects.
# 1. Inspect the status and recreation count (ATTEMPT) of all sandboxes on the node
crictl pods
# 2. View network configuration and IP allocation details for a specific sandbox
crictl inspectp <sandbox-id>
# 3. Check cluster-reported Pod Conditions and Pod IP
kubectl describe pod <pod-name>
kubectl get pod <pod-name> -o jsonpath='{.status.podIP}'
When a Pod is stuck in ContainerCreating and event logs report network setup timeouts, the root cause almost always lies within the RunPodSandbox phase—such as failed CNI plugin execution or exhausted IPAM (IP Address Management) allocations. The first diagnostic step should be checking crictl pods and runtime logs directly on the node.
NOTE
Further reading: A Beginner’s Guide to Container Runtimes (Part 1): Core Mechanics
Clarifying Terminology: CRI Sandboxes vs. Security Sandboxes
In the cloud-native ecosystem, the term “sandbox” surfaces across different architectural levels and broadly covers two distinct categories:
| Dimension | CRI PodSandbox (Topic of this Article) | Sandboxed Runtime (Security Isolation) |
|---|---|---|
| Core Role | Kubernetes resource aggregation and lifecycle anchor | Hardened workload security boundary |
| Implementation | Linux namespaces, cgroups, or pause containers | Userspace kernel (gVisor / runsc) or lightweight microVMs (Kata Containers) |
| Integration Level | Core CRI RuntimeService specification | Configured via Kubernetes RuntimeClass handlers |
| Primary Goal | Share networking and resources across containers in a Pod | Intercept sensitive syscalls; prevent container escapes and multi-tenant interference |
Introducing security sandbox technologies like gVisor or Kata Containers merely changes the isolation technology filling the sandbox slot; it leaves the CRI’s PodSandbox abstraction completely untouched.
The kubelet lifecycle call chain and the RunPodSandbox interface remain identical, which is what keeps the Kubernetes control plane consistent and extensible.