Images, Layers, Content-Addressable Storage, Manifests, Config Objects, and Image Identity: Configuration, Design Choices, and Tradeoffs

1. Start with the decision, not the command

Image design choices change who can reproduce a deployment, how fast security updates arrive, which platforms are supported, how much local content is retained, and how easy an incident is to explain. The right choice depends on whether you are optimizing a developer loop, a release artifact, a fleet promotion, a debugging environment, or a constrained edge target.

For every choice in this lesson, keep four pieces of evidence together: human reference, immutable digest, platform, and the policy/operational reason for the choice.

2. Tag convenience versus digest pinning

Pinning is not the same as never updating. A mature process makes updates explicit: resolve a new upstream release, review/test it, capture the new digest, and change the pinned reference in version control. That gives both freshness and auditability.

3. Single-platform manifest versus multi-platform index

A single-platform image can be simpler and completely adequate when the execution fleet is intentionally homogeneous. A multi-platform index is valuable when one release name must serve multiple OS/architecture combinations. The cost is more evidence: every supported platform has its own manifest and potentially different config/layer digests.

flowchart TD
  A[acme/app:2.4 tag] --> B[index digest]
  B -- linux/amd64 --> C[manifest A digest]
  B -- linux/arm64 --> D[manifest B digest]
  C --> E[amd64 config + layers]
  D --> F[arm64 config + layers]
            

Promotion policy should say whether approval binds to the index as a whole or to a specific child manifest. For a heterogeneous fleet, the index digest is a useful release subject; incident evidence should still record which platform child actually ran.

4. Minimal base versus compatibility-rich base

Do not compare bases only by compressed size. Record architecture support, libc/runtime compatibility, update cadence, provenance/source policy, CVE maintenance, non-root support, and operational debug plan.

5. Retain useful content or clean it?

Local image content accelerates rebuilds, pulls, and rollback, but consumes disk. Cleanup is therefore an ownership problem before it is a disk-space command. Ask which references, stopped containers, builders, and snapshots depend on the content and whether rollback requires it.

Avoid “free space now” habits such as broad docker system prune -a --volumes. Prefer read-only accounting first (docker system df, image lists, builder disk usage), then remove an exact lab-owned reference or builder/cache scope whose consequences are understood.

6. Local store architecture affects capability, not release identity

Fresh Engine 29 installs default to the containerd image store and can retain multi-platform images locally. Upgraded daemons may still use the classic store. That changes local capability and disk layout, but your release process should still anchor on OCI identities from the registry and observed local identity. Do not make “which directory contains the layers” part of application release logic.

7. Worked scenario: one release for amd64 and arm64

Suppose a team publishes registry.example.test/payments:2.4 for Linux/amd64 and Linux/arm64. Developers want a readable tag; production needs immutable rollback; security wants scan/attestation subjects; operations wants to know which child ran during an incident.

1. Publish: produce one multi-platform index and record its digest as the release identity.
2. Review: inspect the index and verify both required child manifests exist.
3. Promote: move environment metadata or deployment configuration to the approved index digest; do not rebuild the release.
4. Run: each host/runtime selects its compatible platform manifest.
5. Observe: retain index digest, selected platform, child manifest/config/local image identity, container ID, and deployment timestamp.
6. Rollback: select the prior approved index digest instead of guessing which tag used to point there.

The same design can keep :2.4 for humans while treating the digest as the release's immutable key.

8. Decision table

9. Supply-chain and rollback implications

A digest proves content identity, not trustworthiness. It does not tell you who built the image, whether dependencies are vulnerable, whether the source was reviewed, or whether the image is authorized for production. Those are later supply-chain controls. Digest identity is the join key that lets scans, SBOMs, provenance, signatures, approvals, and deployment evidence refer to the same subject.

Likewise, a minimal image can still contain a critical vulnerability, and a signed image can still be operationally broken. Keep identity, security signals, and runtime health separate.

Knowledge check

Official references and version notes

• Docker: What is an image? — image/layer fundamentals and local image inspection.
• docker image pull — content-addressable image storage, shared layers, pull digests, and pulling by digest.
• docker image inspect — local image metadata, IDs, RepoDigests, rootfs data, and platform-aware inspection.
• docker image ls — repository/tag presentation, image IDs, and digest display.
• docker image history — build-history presentation and platform selection.
• docker buildx imagetools inspect — registry-side image index/manifest inspection without assuming the local store contains every platform.
• containerd image store with Docker Engine — Engine 29 fresh-install default, snapshotters, multi-platform local storage, and upgrade/userns-remap caveats.
• Docker storage drivers — layer sharing, copy-on-write context, history examples, and classic storage-driver behavior.
• OCI Image Specification v1.1.1 — current stable OCI image-format release used as the chapter's standards baseline.
• OCI image manifest — config descriptor, ordered layer descriptors, media types, and single-image/platform semantics.
• OCI image index — higher-level descriptor set used for multi-platform publication.
• OCI image configuration — runtime configuration, rootfs DiffIDs, history, and ImageID-related content.
• OCI content descriptors — media type, digest, size, platform, and content-verification semantics.