Sandbox controller

A sandbox is a unit of shared isolation: in CRI terms, a "pod sandbox" is the network namespace, IPC namespace, and PID namespace shared by all containers in a Kubernetes pod. containerd has a generic Sandbox plugin type so that microVMs and other isolation primitives can plug in too.

Purpose

• Manage the lifecycle of a sandbox (Create / Start / Status / Stop / Shutdown / Wait).
• Provide a place to host containers that share namespaces.
• Decouple "the thing that owns the netns" from "the thing that runs containers", so a microVM-backed sandbox can host many containers.

Pieces

Code	Role
api/services/sandbox/v1/	gRPC and ttrpc proto definitions
core/sandbox/	The Sandbox interface and store abstractions
core/sandbox/proxy/	gRPC client wrapper that turns a remote sandbox controller into a local interface
plugins/sandbox/	Built-in sandbox controller(s)
plugins/services/sandbox/	gRPC sandbox service registration
internal/cri/server/podsandbox/	The CRI-specific sandbox controller that runs a pause container per pod

Key abstractions

Type	File	Purpose
sandbox.Sandbox	core/sandbox/sandbox.go	The metadata record
sandbox.Controller	core/sandbox/controller.go	Create/Start/Stop/Status
sandbox.Store	core/sandbox/store.go	Persistence for sandbox records
podsandbox.Controller	internal/cri/server/podsandbox/	The CRI built-in controller; spawns a pause container as the sandbox shim

Plugin types

Two related plugin types from plugins/types.go:

SandboxStorePlugin       plugin.Type = "io.containerd.sandbox.store.v1"
SandboxControllerPlugin  plugin.Type = "io.containerd.sandbox.controller.v1"
PodSandboxPlugin         plugin.Type = "io.containerd.podsandbox.controller.v1"

SandboxStorePlugin persists sandbox metadata (typically backed by the bbolt metadata store). SandboxControllerPlugin is the lifecycle controller. PodSandboxPlugin is the special CRI-specific one.

How a CRI sandbox starts

sequenceDiagram
    participant Kubelet
    participant CRI as CRI service
    participant Ctl as sandbox controller (podsandbox)
    participant Runtime as runtime v2

    Kubelet->>CRI: RunPodSandbox(config)
    CRI->>Ctl: Create(sandbox_id, config)
    Ctl->>Runtime: Create(pause container)
    Runtime-->>Ctl: started
    Ctl->>Ctl: setup CNI on netns
    CRI-->>Kubelet: Sandbox running
    Kubelet->>CRI: CreateContainer(image, sandbox_id)
    CRI->>Runtime: Create container (joins sandbox netns)
    CRI-->>Kubelet: Container running

The pause container is a tiny binary that holds the netns open while real containers are running. The CRI plugin's cni_conf_syncer (internal/cri/server/cni_conf_syncer.go) watches for CNI config changes and reloads CNI plugins.

Microvms / non-pause sandboxes

The SandboxControllerPlugin interface is intentionally generic. A microVM-style runtime registers its own controller plugin and runtime.Sandbox directives describe how the sandbox shim is started. The runtime v2 manager spawns the sandbox-aware shim binary, which can host multiple containers.

Proxying

core/sandbox/proxy/ lets a sandbox controller live in another process. The wiring is done in cmd/containerd/server/server.go via the [proxy_plugins.<name>] configuration with type = "sandbox".

Entry points for modification

• New sandbox controller: implement core/sandbox/controller.go and register a SandboxControllerPlugin.
• Modify CRI sandbox behavior: see internal/cri/server/podsandbox/.
• Add per-sandbox metadata: extend the bbolt schema in core/metadata/sandboxes.go.

For the CRI side that drives the controller, see CRI plugin.