Container Image

A container image is the package a container is started from: a filesystem plus the defaults for running it. It is defined by specification rather than by any product — the OCI image format “defines an OCI Image, consisting of an image manifest, an image index (optional), a set of filesystem layers, and a configuration,” with the goal “to enable the creation of interoperable tools for building, transporting, and preparing a container image to run.” Quotations below are from that specification and its layer document, read in September 2026.

The four parts

Part	What it holds
Manifest	“Metadata about the contents and dependencies of the image including the content-addressable identity of one or more filesystem layer changeset archives that will be unpacked to make up the final runnable filesystem”
Layers	Those changeset archives — the filesystem content, in pieces
Configuration	“Information such as application arguments, environments, etc.” — the defaults for running it
Index (optional)	“A higher-level manifest which points to a list of manifests and descriptors,” typically “different implementations of the image, possibly varying by platform”

The index is why one name can serve both an x86 and an ARM machine: the client picks the manifest matching its platform. And note that the manifest references layers by “content-addressable identity” — the image’s structure is built on hashes rather than on names, which matters in a moment.

A layer is a changeset, not a snapshot

This is the fact that changes how you build images. The layer specification describes “how to serialize a filesystem and filesystem changes like removed files into a blob called a layer. One or more layers are applied on top of each other to create a complete filesystem.”

Three kinds of change can appear: “Additions, Modifications, Removals.” The first two are stored the same way — the new content is in the archive. The third is different, and the difference is the important part: “removals are represented using ‘whiteout’ file entries.”

So a deletion is a note in a later layer saying that a path is gone. The bytes in the earlier layer are untouched. They are still in the image, still transferred when the image is pulled, and still readable by anyone who can inspect the layers.

Which makes a common build pattern a credential leak. Copy a key file in, use it, delete it in a later step, and you have published the key — the deletion is a whiteout sitting above it. The same applies to anything sensitive that touched the filesystem during the build: source archives, private keys, a configuration file containing a token.

Two consequences worth acting on. Do not add it in the first place — pass secrets at run time or use a build mechanism that does not persist them into a layer, which is the general rule in secrets management appearing in a form that is easy to miss. And if it has already shipped, editing the image does not help; rotate the credential.

Layers also decide transfer and cache behaviour

Since layers are identified by content, two images built on the same base share that base: it is stored and transferred once. That is why base image choice affects pull times across a whole fleet rather than one service, and why a large base is a cost paid repeatedly.

Order matters for the same reason. A layer changes when anything in it changes, and every layer above a changed layer must be rebuilt and re-transferred. So the ordering rule is to put what rarely changes underneath what changes often — dependencies below application code, not above it. Getting this backwards means every one-line change ships the whole dependency set again.

Names are not identities

The specification’s summary of an image’s life names both identifiers in one sentence: “once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an OCI Runtime Bundle.”

Discovered by name, verified by hash. A tag is a mutable pointer — the same tag can be pushed again tomorrow at different content — while the digest names exactly one set of bytes and cannot be reissued. So deployments should reference the digest and leave tags as a convenience for people, which is the same rule that applies to any build artifact and is easier to violate here because tags are so pleasant to type.

Because content is verifiable and signatures can be attached, the image is a sensible place to enforce supply-chain controls — checking what you are about to run instead of trusting a name. That is the subject of software supply chain security, and where two builds of one source must produce identical bytes, see reproducible build.

What the image does not contain

The configuration inside supplies defaults — the command, arguments, declared environment. Everything about a particular execution is supplied when a container is created, and one omission is worth stating explicitly because it is assumed otherwise: an image contains no isolation. Namespaces, resource limits, and the effective user are arguments to running, not contents of the package. The same image is safe or unsafe depending on how it is launched — see container for what those choices are.

Nor does it contain durable state. The filesystem is disposable, so anything that must survive a restart belongs on mounted storage, and configuration that varies by environment belongs outside the image so that the thing you tested is the thing you deploy.

Finally, one practice this structure supports: because an image is versioned and replaceable, keeping software current means building a new image and replacing what runs rather than patching in place — the operational discipline covered under golden image, which applies to machine images and container images alike. The specifications that make all of this interoperable are the OCI‘s, and how the pieces fit together is worked through in Isolated From What, Exactly.

References: OCI Image Format Specification; OCI Image Layer Filesystem Changeset. Both read September 2026.