OCI Runtime Specification

In this lesson, you will learn how the OCI Runtime Specification acts as the definitive translation layer between a human-readable config.json and the opaque, low-level Linux kernel primitives that isolate your containers.

Bridging Intent and Execution

When you launch a container, you don't interact with the kernel directly; you provide a declarative config.json file. The OCI Runtime Specification (the runtime-spec) defines exactly how the runtime—like runc—must interpret these fields to map them into kernel system calls.

The magic happens when the runtime parses the linux object within your configuration. It performs a "semantic mapping" of these settings into the specific namespace and cgroup APIs provided by the kernel.

Translating Configuration to Kernel Primitives

Consider how the specification handles namespace isolation. In your config.json, you might define a linux.namespaces array:

{
  "linux": {
    "namespaces": [
      { "type": "pid" },
      { "type": "network" }
    ]
  }
}

When the runtime encounters this, it doesn't just "enable" them. It executes a specific sequence:

1. unshare(): The runtime calls unshare(CLONE_NEWPID | CLONE_NEWNET) to carve out new process and network namespaces for the process that will become init.
2. setns(): If you requested to join an existing container's namespace, the runtime opens the file descriptor in /proc/[pid]/ns/ and invokes setns().
3. Cgroup Mapping: The runtime maps the linux.resources block to the cgroupfs hierarchy. For instance, a memory limit defined in the OCI spec is translated into writing a byte value to /sys/fs/cgroup/memory/[container_id]/memory.limit_in_bytes.

The OCI specification ensures that regardless of which runtime you use (e.g., runc, crun, or youki), the resulting container environment is consistent. It dictates the lifecycle (Create -> Start -> Run -> Delete) and mandates that the runtime translates your high-level JSON policy into the precise clone() flags, mount namespaces, and cgroup controllers the Linux kernel requires to enforce isolation.

By standardizing this translation, the OCI spec prevents vendor lock-in and ensures that security policies—such as those enforced by SELinux or AppArmor—are applied to the container process before it ever executes its entrypoint.

Key Takeaway: The OCI Runtime Specification functions as the standardized translation engine that converts high-level JSON intent into the specific syscalls and filesystem writes required to manipulate Linux namespaces and cgroups.