Container Image

A container image packages a filesystem with execution defaults. The OCI image specification separates that package into a manifest, configuration, filesystem layers, and an optional index. Compatible tools use those structures to transfer content and prepare it for execution.

The four parts

Part	What it holds
Manifest	References the configuration and filesystem layer blobs by digest
Layers	Filesystem additions, modifications, and removal records, applied in order
Configuration	Execution defaults such as command, environment, and user
Index (optional)	References manifests, often for different operating systems or CPU architectures

An index can group images for platforms such as Linux x86-64 and ARM64. A compatible client selects an appropriate manifest. Each manifest references the configuration and layers by digest, tying the selected image to its content.

A layer is a changeset, not a snapshot

An OCI layer encodes changes to a filesystem. Applying successive layers assembles the filesystem a container starts from.

Additions and modifications store file content in the layer archive. Removals use whiteout entries to hide paths from earlier layers.

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.

A credential copied into a distributed layer remains recoverable if a later layer deletes it. This applies to data retained in the final image’s layers or configuration, not every file used during a build. Secret mounts can avoid recording secret bytes, and a build stage may be absent from the final image. Neither condition proves that logs, outputs, or exported caches are free of sensitive data.

Use build secret mechanisms without copying secrets into persistent outputs, and apply secrets management to caches and logs as well as images. Revoke or rotate exposed credentials and address retained copies. Disclosure of other confidential material, such as source archives, requires its own response; changing the image cannot undo disclosure.

Layers also decide transfer and cache behavior

Content-addressed layers allow a registry or a node’s content store to reuse blobs it already has. Two images with the same base can benefit from that reuse. Separate nodes may still download the base separately, and cache eviction or storage scope can require another transfer. There is no fleet-wide guarantee of one copy or one transfer.

For a sequential Docker build, put stable dependency instructions before frequently changing application code. A cache miss generally invalidates subsequent instruction results. Those steps may execute again, but transfer depends on the resulting blob digests and whether the destination already holds them. Rebuilding a step and retransmitting its output are separate events.

Names are not identities

Registries associate human-readable names with manifests or indexes, while digests identify their content. Signature verification adds a separate decision about whether to trust the publisher or provenance.

A tag can move to different content. A digest can be reproduced by recreating identical bytes; it is not a unique build-invocation identifier. Under normal cryptographic verification, changed bytes do not verify against the prior digest. Pin a build artifact by its content identity and retain its provenance separately. If the digest names a multi-platform index, also record which platform manifest was executed.

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 image supplies command, environment, and user defaults. For example, config.User set to 1000 is the default identity when no user override is supplied; a launch-time override of 0 changes it. Namespaces and resource limits are runtime settings, but image contents and defaults also affect security. Review the effective configuration and host mapping together with the image; see container for the isolation mechanisms.

Docker keeps the writable layer across a stop/start of the same container and removes it when that container is destroyed. State needed after replacement belongs in storage with a suitable independent lifecycle, such as a retained volume or external database. A tmpfs mount is temporary and loses data on stop. Keep environment-specific configuration outside the image when promoting the same tested package to compatible environments.

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
• OCI Image Configuration
• Docker build secrets
• Docker build cache invalidation
• OCI Distribution specification
• Docker storage
• Docker tmpfs mounts