When reading OCI documentation, separate three questions: what an image contains, how a registry transfers it, and how a runtime starts a container from it. The Open Container Initiative publishes distinct Image, Distribution, and Runtime Specifications. The OCI overview sketches the lifecycle; containerd’s content-flow guide follows an image from a registry to a filesystem ready for execution.

Three specifications, three boundaries

  • Image Specification describes the structure of image data such as manifests, configuration, and layers.
  • Distribution Specification defines an interoperable registry API for discovering, uploading, and downloading images and artifacts. It does not prescribe every detail of registry storage or product architecture.
  • Runtime Specification describes the configuration and filesystem bundle used to create and run a container process.

A pull involves the Distribution and Image perspectives; starting a local process involves the Runtime perspective. OCI conformance alone does not specify a product’s scheduler, networking design, or complete authorization policy.

Follow a tag to a running filesystem

A name such as example/app:stable is convenient, but it is a reference that must be resolved. As containerd’s guide explains, a registry can return a manifest or an index pointing to manifests for multiple platforms. If it is an index, the client selects the manifest matching the target operating system and architecture, then retrieves the config and layers by their digests. The layers are unpacked in order into snapshots, and a writable filesystem is prepared for the container.

This sequence shows why “run the image” spans several boundaries. Two hosts using the same tag may select different platform manifests. A successful registry pull does not prove that unpacking or process creation succeeded. During an incident, check the resolved digest and platform, then inspect layer unpacking and runtime startup as separate stages.

A runtime interface is not the same as a daemon

The OCI Runtime Specification describes a low-level bundle and configuration for execution. A higher-level project such as containerd can coordinate image transfer, storage, and lifecycle, then invoke an OCI-compatible runtime. Distinguishing the standard interface from the daemon helps locate whether a failure occurred during image handling, setup, or process launch.

Windows containers do not always use Hyper-V isolation

OCI’s runtime specification includes Windows-specific configuration. Its Windows configuration document describes the use of Windows Host Compute Service APIs. The optional hyperv field means the container must run with Hyper-V isolation; when the field is omitted, the document specifies Windows Server container isolation. It is therefore inaccurate to describe every Windows container as a Linux VM. Check the host OS, runtime, and deployment configuration to understand the isolation boundary.

A practical troubleshooting order

For a registry failure, inspect the Distribution API and registry response. For a platform mismatch or missing layer, inspect the image index, manifest, and digests. If the process fails to start, inspect the runtime bundle, host-specific settings, and execution engine. Separating these layers replaces the vague diagnosis “OCI is broken” with a testable failure boundary.

Sources