4.6 Kubernetes Pod Sandbox Execution

Kubernetes Pod Sandbox Execution is the runtime process of instantiating the isolated execution environment that underlies every pod, established before any application container is created and shared by all containers within that pod. It encompasses the creation of shared Linux namespaces, the invocation of network plugins, and the maintenance of a stable execution context that persists across individual container restarts within the same pod.

The Purpose of the Sandbox Layer

Isolation Boundary for the Pod

A pod is not a single process but a group of one or more containers that need to share certain resources, most importantly network identity. The sandbox provides the shared namespace context, typically the network namespace and sometimes the IPC namespace, that all containers in the pod attach to, giving them a common localhost and a single IP address.

Decoupling Pod Identity from Container Identity

Because the sandbox is created independently of the application containers, a container can crash and be recreated without disturbing the pod's network identity or IP address. The sandbox persists as the stable anchor, while individual containers within it can be replaced freely.

Sandbox Creation Workflow

RunPodSandbox CRI Call

When the kubelet determines a pod needs to start, it issues a RunPodSandbox call through the Container Runtime Interface to the configured runtime, such as containerd or CRI-O. This call includes pod-level metadata, security context settings, and network configuration derived from the pod spec.

Pause Container Mechanics

Under the hood, most container runtimes implement the sandbox using a minimal "pause" container, a small binary whose only job is to hold open the shared namespaces for the lifetime of the sandbox. This pause process becomes PID 1 within the shared namespace context and does nothing beyond waiting, ensuring the namespaces remain valid even if application containers are still being created or restarted.

CNI Plugin Invocation

As part of sandbox creation, the runtime invokes the configured CNI plugin, passing it the sandbox's network namespace path. The CNI plugin allocates an IP address, configures virtual network interfaces, sets up routes, and in the case of overlay or CNI-managed networks, attaches the sandbox to the cluster's pod network.

Sandbox State and Lifecycle

Sandbox States

A pod sandbox can exist in states including SANDBOX_READY and SANDBOX_NOTREADY. The kubelet queries sandbox state through PodSandboxStatus calls to determine whether existing sandboxes can be reused or must be torn down and recreated.

Sandbox Reuse Across Container Restarts

If a container within a pod crashes and needs restarting, the kubelet does not necessarily tear down the sandbox. As long as the sandbox remains healthy and its network configuration is intact, the kubelet reuses it and simply creates a new container instance attached to the existing sandbox.

Sandbox Teardown

When a pod is deleted, or when the sandbox itself becomes unhealthy, the kubelet issues a StopPodSandbox call followed by RemovePodSandbox. Stopping releases the network resources by invoking the CNI plugin's teardown operation, while removal cleans up any remaining sandbox metadata and storage.

Networking Details Within the Sandbox

IP Address Assignment

The IP address assigned to the sandbox becomes the pod's IP address for as long as the sandbox exists. This assignment is recorded by the runtime and reported back to the kubelet, which relays it to the API server as part of the pod's status.

DNS and Hosts File Configuration

During sandbox setup, the runtime, guided by the kubelet, configures DNS resolution settings and an /etc/hosts file that will be shared by mount into every container in the pod, ensuring consistent name resolution behavior across all containers in the same pod.

Port Mapping

If the pod spec declares host port mappings, these are established during sandbox creation as well, associating specific host node ports with the sandbox's network namespace so that traffic arriving on the host can reach the appropriate pod.

Failure Modes and Recovery

Sandbox Creation Failures

If CNI plugin invocation fails, for example due to IP address exhaustion in the pod CIDR range or a misconfigured network plugin, sandbox creation fails and the kubelet reports the pod as being in a ContainerCreating state indefinitely, retrying sandbox creation on a backoff schedule.

Detecting Broken Sandboxes

If the pause process dies unexpectedly, or the runtime reports the sandbox as not ready during a routine PodSandboxStatus check, the kubelet treats the sandbox as broken. It then coordinates a full teardown and recreation cycle, which also restarts every container within that pod, since the shared namespace state itself has been lost.

Garbage Collection

Terminated sandboxes that are no longer associated with any running pod are periodically garbage collected by the kubelet, which calls RemovePodSandbox to reclaim any disk and metadata resources still held by the runtime for that sandbox.