OCI Runtime Spec: The 'How to Run' Standard for Containers

WHY IT EXISTS: Before the Open Container Initiative (OCI), the container ecosystem was fragmented with competing formats from Docker, CoreOS, and others. This threatened portability. The OCI was created to establish open standards, and the Runtime Spec specifically solves the problem of ensuring a container runs the same way everywhere.

THE MENTAL MODEL: Think of the OCI Runtime Spec as the low-level API between a container manager (like containerd) and the program that actually runs the container (like runc). The manager prepares a 'bundle' on disk—the container's filesystem plus a config.json file—and tells the runtime, "Here's a bundle, run it according to these standard instructions."

HOW IT WORKS: The spec defines a standard for a 'filesystem bundle'. This bundle is a directory containing the container's root filesystem and, at its root, a file named config.json. This JSON file details everything about the container's desired state: the command to execute, environment variables, resource limits, mounts, and platform-specific configurations like Linux namespaces or Windows isolation settings. The spec also standardizes the container's lifecycle with commands like create, start, kill, and delete that a runtime must implement.

WHEN TO USE IT: As an application developer, you don't use the spec directly. You benefit from it whenever you use Docker, Podman, or Kubernetes. It's the reason a container image built on one machine works predictably on another, even if the underlying runtime software is different. It guarantees interoperability and prevents vendor lock-in for container execution.

WHEN NOT TO USE IT: The spec is not a user-facing tool. You should not be editing config.json files by hand unless you are building or debugging a container engine itself. For defining and running applications, always use higher-level abstractions like a Dockerfile, docker-compose.yml, or Kubernetes manifests.

ONE CANONICAL EXAMPLE: When Kubernetes wants to start a pod, its node agent (the kubelet) asks the Container Runtime Interface (CRI) implementation, like containerd, to run a container. containerd unpacks the OCI image into a filesystem bundle and generates a compliant config.json. It then invokes a low-level OCI runtime like runc, passing the path to the bundle. runc reads config.json, creates the sandboxed environment using the specified kernel features, and executes the container process inside it.