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:

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.

  1. CRI Interface: PodSandbox
    1. Linux Namespace / cgroupcontainerd / CRI-O
    1. 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:

  1. The kubelet requests the runtime to create a sandbox via CRI: the kubelet initiates RunPodSandbox over gRPC and never directly interacts with underlying network devices.
  2. The runtime invokes CNI: Prior to the removal of dockershim in Kubernetes 1.24, the kubelet invoked CNI directly using --cni-bin-dir and --network-plugin. Since 1.24, CNI management has moved entirely into the CRI runtime.
  3. 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; the eth0 interface 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:

# 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.


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:

DimensionCRI PodSandbox (Topic of this Article)Sandboxed Runtime (Security Isolation)
Core RoleKubernetes resource aggregation and lifecycle anchorHardened workload security boundary
ImplementationLinux namespaces, cgroups, or pause containersUserspace kernel (gVisor / runsc) or lightweight microVMs (Kata Containers)
Integration LevelCore CRI RuntimeService specificationConfigured via Kubernetes RuntimeClass handlers
Primary GoalShare networking and resources across containers in a PodIntercept 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.