The OCI Standard

The reason a driftwood/web image you built with docker build runs unchanged under Podman, containerd, and Kubernetes — and pushes to Docker Hub, GHCR, or registry.driftwood.example without translation — is that none of those tools invented their own image format. They all implement the Open Container Initiative (OCI) specs.

"Docker images" are really OCI images. Docker donated the format to a vendor-neutral body in 2015, and that act is the foundation of the whole book's portability claim. Every time this course said "build once, run anywhere," it was leaning on a standard it had not yet named — this topic names it.

Three Specs, One Contract

OCI is not one document but three, and together they cover the full lifecycle: build, run, and ship. The image-spec defines how an image is laid out — its manifest, config, and layers. The runtime-spec defines how a runtime turns an unpacked image into a running container: the namespaces, cgroups, and mounts. The distribution-spec defines how registries serve images over HTTP. Three contracts, one artifact moving through all of them.

The split matters because it lets different tools own different stages without colliding. A builder writes the image-spec format; a runtime reads the runtime-spec bundle; a registry speaks the distribution-spec API. Each can be a separate project from a separate vendor, and they interoperate because they agree on these three documents rather than on a single product.

Image-Spec — Why Any Tool Reads Your Image

The manifest, config, and layer format you met back in Chapter 2 is the OCI image-spec. Because Docker, Podman, and containerd agree on it byte-for-byte, the image you built is the exact artifact every other tool consumes — no conversion, no repacking, no import step. The layers are content-addressed blobs; the config records the entrypoint, working dir, and user; the manifest ties them together. Any compliant tool reads all three the same way.

Runtime-Spec — The Bundle Any Runtime Runs

The runtime-spec describes a filesystem bundle — an unpacked root filesystem plus a config.json listing the namespaces, cgroups, mounts, and the process to exec. runc, covered in the next topic, is the reference implementation, but it is just one implementation of a written contract. That is exactly why crun, gVisor, and Kata can be drop-in replacements: they all read the same bundle and honor the same config.json, so you swap the runtime without touching the image.

Distribution-Spec — Why Every Registry Speaks the Same API

The distribution-spec standardizes the pull and push HTTP API, so docker push registry.driftwood.example/driftwood/web:1.4.0 and the same push to Docker Hub or ECR hit identical endpoints. A registry is OCI-compliant or it is not, and compliance is the only thing that matters when you pick one. The product name on the registry is marketing; the distribution-spec is what decides whether your client can push a multi-arch manifest to it.

Where Docker Sits Now

Docker is one implementation of these specs, not the definition of them. The headline portability of "build once, run anywhere" is an OCI property you have been relying on since Chapter 2 without it being named. Docker Engine, BuildKit, and the Docker CLI are the spine this book taught because they are the way most people build and run containers — but the artifact they produce belongs to the standard, not to Docker.

This reframes the rest of the chapter. containerd and runc are OCI runtime implementations; Podman and Buildah are OCI build-and-run tools; Kubernetes consumes OCI images through containerd. Once you reason in terms of the three specs, every alternative tool stops being a competitor to Docker and becomes another reader of the same driftwood/web artifact.