OCI Image Manifest: The Recipe for a Container Image

WHY IT EXISTS: To provide a standardized, content-addressable "bill of materials" for a container image. This allows runtimes to verify image integrity and ensures that an image tag points to a consistent set of components for a given platform, solving the problem of ambiguity in what an image contains.

THE MENTAL MODEL: Think of an OCI Image Index as a restaurant menu listing the same dish prepared for different dietary needs (e.g., "Pizza," "Gluten-Free Pizza"). The OCI Image Manifest is the specific recipe for one of those versions, detailing the exact ingredients (layers) and cooking instructions (config).

HOW IT WORKS: The manifest is a JSON file. Its key fields are config, a descriptor pointing to a JSON file with runtime settings like environment variables and entrypoint, and layers, an ordered list of descriptors pointing to the compressed filesystem tarballs (blobs). The manifest, its config, and its layers are all content-addressable by their cryptographic hashes, ensuring immutability and verifiability.

WHEN TO USE IT: You interact with manifests indirectly every time you pull, push, or run a container image. Tools like docker manifest inspect or skopeo inspect let you view the manifest directly to debug image issues or understand its composition. It is the ground truth for what constitutes a specific image variant.

WHEN NOT TO USE IT: You don't manually create or edit image manifests; build tools like Docker or Buildah generate them. For defining multi-architecture images, you work with an Image Index, which groups multiple manifests, rather than interacting with a single manifest directly.

ONE CANONICAL EXAMPLE: When you run docker pull my-app:latest on an M1 Mac (linux/arm64), the Docker client first fetches the image index for my-app:latest. It finds the entry for linux/arm64 and gets the hash of its manifest. It then fetches that specific manifest, which tells it the hashes of the arm64-compatible config file and layers to download and assemble.