OCI and Runtime Architecture (containerd, runc)
On this page
Operational Goal
- Know which layer is failing: image → runtime → kernel → networking/storage.
- Collect evidence fast: runtime version, cgroups, mounts, namespaces.
Runtime Stack (Ops Mental Model)
- OCI Image Spec: how an image is packaged (layers, config).
- OCI Runtime Spec: how a container is started (process, namespaces, cgroups).
- runc: low-level runtime that creates the container process.
- containerd: manages images, snapshots, and container lifecycle.
- CRI: Kubernetes talks to container runtimes via CRI (often through containerd).
Identify What You Are Running
# Docker engine details (if Docker is installed) docker version docker info | head -80 # containerd (common on Kubernetes nodes) containerd --version 2>/dev/null || true ctr version 2>/dev/null || true # runc version runc --version 2>/dev/null || true
Where Failures Usually Happen
- Image pull: auth, registry, DNS, MTU, proxy issues.
- Create: invalid config, missing mounts, seccomp/caps blocked.
- Start: entrypoint crashes, permission denied, wrong user, missing libs.
- Runtime: OOM, CPU throttling, filesystem full, network drops.
Evidence Pack: Runtime + Kernel
uname -a cat /etc/os-release 2>/dev/null || true mount | head -80 lsmod | head -40
Failure Modes
- Works on laptop, fails on node: kernel/seccomp/cgroup differences.
- Random start failures: overlay snapshot corruption or disk pressure.
- Slow pulls: registry throttling, DNS cache, MTU fragmentation.