The OCI ecosystem · Docker & Containers

The phrase “Docker image” is misleading. What you actually ship is an OCI image. What actually runs the container is an OCI runtime. The “Docker registry” protocol is the OCI distribution spec. None of these are owned by Docker, Inc.; they are maintained by the Open Container Initiative, a project under the Linux Foundation.

This separation is the most important reason your Docker skills transfer to Podman, CRI-O, containerd, Kubernetes, and everything else. OCI is the lingua franca.

The three OCI specifications

flowchart LR
  Build[Build] -->|image-spec| Registry[(Registry)]
  Registry -->|distribution-spec| Host[Container host]
  Host -->|runtime-spec| Process[Running process]

1. OCI Image Format Specification

Defines what an “image” is, as content. Four kinds of object, all content-addressed by the SHA-256 of their own bytes and referenced by descriptors carrying a media type, a digest and a size:

An index (sometimes called a manifest list) — a list of manifests, each tagged with a platform. This is what makes an image multi-platform.
A manifest — one platform’s image: a descriptor for the config and an ordered list of descriptors for the layers.
A config — JSON describing the intended runtime parameters: Entrypoint, Cmd, Env, User, WorkingDir, Labels, ExposedPorts, plus the rootfs.diff_ids and the history array.
Layers — tar archives (usually gzip-compressed) representing filesystem changesets, including the .wh. whiteout convention for deletions.

Where it stops. The image spec describes what the config means as intent. It does not say how any of it is enforced. ExposedPorts publishes nothing. Volumes mounts nothing. User is a string, and nothing in the spec says how to resolve a name to a UID. Those are all decisions for whatever runs the image.

2. OCI Runtime Specification

Note carefully what it does not take as input: an image. The runtime spec has no concept of images, registries, layers or tags.

It defines a bundle: a directory containing a config.json and a rootfs/ directory. It defines what goes in that config.json — the namespaces to create or join, the cgroup path and resource limits, the capability sets, the seccomp profile, the mounts, the process to execute, its arguments, environment, and UID/GID. And it defines a lifecycle: create, start, kill, delete, plus a state query.

A conforming runtime given a bundle is expected to:

Set up namespaces, cgroups, capabilities, seccomp, AppArmor or SELinux labels.
Mount the rootfs and the configured mounts, and pivot_root.
execve the configured process as PID 1 of the new PID namespace.

runc is the reference implementation. crun is an alternative written in C with lower overhead. youki is another in Rust.

Where it stops. It says nothing about how the rootfs came to exist, nothing about pulling anything, and — importantly for anyone debugging container networking — nothing about how a network namespace gets an interface, an address or a route. The runtime creates or joins the namespace and stops there. Filling it in is somebody else’s job: dockerd on a Docker host, CNI plugins under Kubernetes.

3. OCI Distribution Specification

Defines the HTTP API a registry serves. Every path begins /v2/; manifests live at /v2/<name>/manifests/<reference> and blobs at /v2/<name>/blobs/<digest>; there is a chunked upload flow for pushing blobs, and a referrers endpoint for discovering artifacts that point at an existing manifest — which is how signatures and attestations are found.

Docker Registry, Harbor, GitLab Container Registry, Amazon ECR, Google Artifact Registry, and Quay all speak this protocol. You can pull from any of them with any OCI client.

Where it stops. Authentication is not in it. The bearer-token flow every registry implements is a de facto standard inherited from Docker, not part of the distribution spec, which is why credential-helper behaviour varies between registries in ways nothing formally governs. Storage layout, replication, retention and garbage collection are all out of scope too — which is why “the registry deleted my blob” is a per-product question.

The seams, which is where the failures are

Nobody's specification: turning an image into a bundle

Read the boundaries above in sequence and a hole appears.

The image spec ends at: here are your compressed layer blobs and a config full of intent.

The runtime spec begins at: here is a rootfs/ directory and a config.json naming a process, namespaces and limits.

Nothing standardises the step in between. Somebody has to:

decompress and apply each layer in order, honouring whiteouts, onto a snapshot — and choose a snapshotter (overlayfs, btrfs, native, stargz) while doing it;
translate the image config’s Entrypoint plus Cmd into process.args, applying the concatenation rules;
translate Env, WorkingDir and User into the runtime config, including resolving a user name by reading /etc/passwd inside the rootfs being assembled;
decide the namespaces, the cgroup path, the default capability set, the default seccomp profile — none of which the image asks for and none of which the runtime spec supplies a default for.

On a Docker host, containerd and dockerd split that work between them. Under Kubernetes, containerd does it driven by the CRI. In Podman, libpod does it. They agree closely enough for images to be portable, and they are not identical — the default seccomp profile, the default capability set, and the handling of an unresolvable USER name are all implementation choices, not spec requirements.

This is the concrete reason a container can run correctly under Docker and fail under another runtime with the same image: the image was the same, and the unspecified translation was not.

You can see the output of that translation directly. The config.json below is the runtime spec’s artifact, generated from your image by containerd, and it is the ground truth for what the container actually got:

Read-only / Safethe bundle— The runtime-spec config generated for a live container. Compare it against the image config to see the translation.

CONTAINER=web
ID=$(docker inspect --format '{{.Id}}' "$CONTAINER")
BUNDLE=/run/containerd/io.containerd.runtime.v2.task/moby/"$ID"
jq '{args: .process.args, user: .process.user, caps: .process.capabilities.effective}' "$BUNDLE"/config.json

Read-only / Safetranslated config— Entrypoint and Cmd have become argv; USER has become numeric IDs; the capability set was chosen by the daemon, not by the image.

# jq '{args: .process.args, user: .process.user}' /run/containerd/io.containerd.runtime.v2.task/moby/3f9a.../config.json

{
"args": [
  "/docker-entrypoint.sh",
  "nginx",
  "-g",
  "daemon off;"
],
"user": {
  "uid": 0,
  "gid": 0,
  "additionalGids": [0]
}
}

Illustrative output

Media types: the part that decides whether a push works

Every descriptor carries a media type, and there are two families for the same objects — the Docker ones (application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json) and the OCI ones (application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json).

They describe structurally compatible objects. A registry that has not been taught about the OCI ones will still reject them.

manifest invalid — on a registry you have pushed to a thousand times

$ docker buildx build --sbom=true --push -t registry.example.internal/myorg/app:1.2.0 .
...
ERROR: failed to push registry.example.internal/myorg/app:1.2.0:
       unexpected status from PUT request: 400 Bad Request: manifest invalid

Credentials are fine. The repository exists. The same pipeline pushed successfully yesterday. The only change was enabling attestations.

Attestations are carried as extra, non-platform entries inside an image index, and an older registry that only understands the Docker manifest-list media type has nowhere to put them and refuses the manifest. The error is generic because the registry is rejecting a document it cannot parse, not a permission.

The first diagnosis is almost always authentication, because “push failed” and 4xx suggest it. Look at what you produced instead:

docker buildx imagetools inspect --raw registry.example.internal/myorg/app:1.1.0 | head -5

If the working image says manifest.list.v2+json and the failing one says image.index.v1+json, the media type is your answer.

Then choose deliberately:

Upgrade the registry. Correct, and often not available this week.
Drop the attestations for that destination: --provenance=false and no --sbom. You lose supply-chain metadata, so record that you did.
Control the media types explicitly on the exporter. The image exporter’s oci-mediatypes option defaults to false, so an ordinary build already emits Docker media types; a build that sets oci-mediatypes=true, or uses --output type=oci, does not.

Whichever you pick, verify by inspecting the pushed manifest, not by the absence of an error.

The runtime stack on a Docker host

What calls what

docker CLI
   ↓ (REST over unix socket or TCP)
dockerd
   ↓ (gRPC)
containerd
   ↓ (CRI for K8s, or containerd's native API)
containerd-shim
   ↓ (fork/exec)
runc (OCI runtime)
   ↓ (clone(2), execve(2))
container process

Docker does not run containers. Docker talks to containerd, which talks to a shim, which talks to runc, which creates the container. When you docker exec, the path is the same. When Kubernetes runs a pod via CRI, it talks directly to containerd, skipping dockerd entirely.

Only the last hop is governed by the runtime spec. Everything above it — the Engine API, the gRPC calls, the shim v2 protocol, the CRI — is a project interface, not an OCI standard. That is why replacing runc is a configuration change and replacing containerd is not.

Swapping the runtime, and proving it took

Because the runtime boundary is a real specification, runc is replaceable. Docker documents registering an alternative in daemon.json:

{
  "runtimes": {
    "youki": {
      "path": "/usr/local/bin/youki"
    }
  }
}

Runtimes that are containerd shims rather than runc drop-ins are registered by shim type instead:

{
  "runtimes": {
    "gvisor": {
      "runtimeType": "io.containerd.runsc.v1",
      "options": {
        "TypeUrl": "io.containerd.runsc.v1.options",
        "ConfigPath": "/etc/containerd/runsc.toml"
      }
    }
  }
}

runtimes is on the daemon’s SIGHUP-reloadable list, so systemctl reload docker picks it up without disturbing anything. Select it per container with --runtime:

Configuration changeuse an alternative runtime— Runs one container under a different OCI runtime. Existing containers keep the runtime they were created with.

docker info --format '{{.Runtimes}} default={{.DefaultRuntime}}'
docker run --rm --runtime youki hello-world
docker inspect --format '{{.HostConfig.Runtime}}' web

The last line is the verification that can fail. A container created before the daemon knew about the new runtime still reports the old one, because the runtime is fixed at creation — so “we switched to gVisor” is a claim about containers created since the change, not about the host.

Why this matters

When a vendor tells you their product is “OCI-compliant,” ask which spec(s). Image-format compliance means the image you build runs elsewhere. Runtime compliance means an OCI runtime can launch it. Distribution compliance means you can pull from their registry with standard tooling. All three together means true portability.

Docker the product is one OCI implementation. Kubernetes is another. Podman is another. Knowing the specs lets you choose the right tool for each job without learning a new container model every time.

The operational payoff is knowing where the guarantees run out. Portability of the image is a specification. Identical behaviour is not: the translation from image to bundle, the default seccomp profile, the default capabilities and the auth flow to the registry are all outside the specs. When something works on one platform and not another, that list is where to look first.

What this means for the rest of the course

The labs in this course target Linux + containerd + runc. They will work with Docker (because Docker talks to containerd) and with Kubernetes (because Kubernetes talks to containerd via CRI). They will also work with Podman if Podman is configured to use the OCI runtime.

The commands we teach (docker run, docker exec, docker build) have equivalents in every OCI runtime. The mental model — namespaces

cgroups + filesystem isolation — does not change.

What if a registry does not implement the referrers API?

Signatures and attestations are attached as separate manifests that refer to the image manifest, and the distribution spec’s referrers endpoint is how a client finds them. A registry that predates it — or has it disabled — returns 404 for that endpoint.

Clients then fall back to a tag-based convention, storing the artifact under a tag derived from the subject digest, something along the lines of sha256-<digest>.sig. It works, and it has two operational consequences worth knowing before you meet them:

Those tags show up in your registry UI and in retention policies. A cleanup job that deletes “untagged or oddly tagged” artefacts will happily delete your signatures, and nothing fails until an admission controller starts rejecting deployments.
Tooling disagrees about the fallback, so a signature written by one client is not always discoverable by another.

Check which mode you are in before you build policy on it — a GET /v2/<name>/referrers/<digest> that returns 404 tells you immediately — and exclude signature artefacts from registry retention rules explicitly rather than by pattern.