Docker/OCI: Image, Layer, Volume, Network, Digest

1. The problem: one “image name” hides several identities

Operationally, app:latest, a content digest, an image manifest, a running container, and files visible inside that container are often collapsed into one idea. That shortcut makes rollback, persistence analysis, and diagnosis unreliable.

The owned artifact is Container Image Runtime Boundary Record v1. It keeps tag/reference, digest, manifest/config/layers, platform, container identity, writable state, mounts, network attachment, and replacement evidence separate.

2. An OCI image is a content-oriented structure

The OCI Image Specification models an image with a manifest, configuration, filesystem layers, and optionally an image index. That interoperable image structure is not the same thing as a running container instance.

Record descriptor/manifest/config/layer evidence separately from runtime observations. If you only have a convenient CLI summary, label any extra conclusion as inference rather than silently promoting it to fact.

3. Descriptors and digests establish a content-identity boundary

An OCI descriptor carries information about referenced content, including media type, size, and digest. The digest participates in verifying referenced content and must remain distinct from a human-readable tag.

A tag is convenient naming. A digest is content-addressed identity evidence. They are useful together, but they do not have the same semantics.

4. A tag is not a digest

A tag or reference is a name/pointer. A digest identifies referenced content by hash. Retagging the same local content changes the human reference without necessarily changing the content digest.

The lab contains a synthetic retag case. The correct conclusion is that tag text changed while content identity remained the same, not that “a new image was automatically created.”

5. Manifest, config, and filesystem layers have distinct roles

An image manifest references configuration and layer descriptors. The config carries image/runtime-oriented configuration metadata; layers represent filesystem changes.

Do not merge manifest digest, config digest, and layer evidence into one field. Each boundary answers a different operational question.

6. An image layer is not the running container writable layer

Docker describes images as immutable and layer-based. Runtime writes go into a writable layer associated with the container rather than mutating the immutable image layers automatically.

If a file is created inside a container and that container is removed, recreating a new container from the same image does not make the old writable-layer state part of the image.

7. Named-volume persistence is a separate boundary

Volumes are designed to keep data outside the lifecycle of an individual container. Replacing a container does not inherently remove a named volume.

The lab includes a replacement case where volume-backed data persists. That proves a storage-boundary observation, not universal application correctness.

8. Bind mounts have different host coupling

A bind mount exposes a host path inside the container. Its lifecycle and coupling differ from a Docker-managed volume.

Record mount type and source explicitly. Seeing a file inside the container is insufficient by itself to prove whether the source is a bind mount, named volume, or writable container layer.

9. Do not guess image index or platform selection

An OCI image index can reference multiple manifests, often for different platforms. A common tag can therefore resolve to a different manifest for a different platform.

The lab includes a synthetic platform variant. If selected-platform or manifest evidence is absent, leave that conclusion OPEN rather than inferring it from the image name.

10. A container is a runtime instance

A container is created from image/config inputs but has its own runtime identity: container ID, process state, writable layer, mounts, and network attachment. Two containers from the same digest can still have different runtime state.

The artifact therefore keeps image identity and container identity in separate fields.

11. Network attachment is not part of the immutable image

Network attachment is a runtime concern. Docker connects containers to explicit networks; that attachment is not derivable from an image filesystem layer or content digest.

The lab supplies direct network attachment evidence. When it is removed, the network conclusion must remain OPEN rather than being guessed from a Dockerfile, tag, or image digest.

12. A digest proves only a bounded property

A matching digest can support the conclusion that referenced bytes match the expected content identity. It does not by itself prove application health, security posture, publisher trust, provenance, or business correctness.

This lesson closes only the container/image/runtime boundary it owns. Signing, provenance, readiness, and orchestration outcomes remain separate topics.

13. Container Image Runtime Boundary Record v1

The artifact records Image Tag/Reference, Image Digest, Platform, Manifest/Config evidence, Layer Evidence, Container ID, Writable-Layer Change, Named Volume, Bind Mount, Network Attachment, Replacement Result, direct observations, inferences, unknowns, and the final bounded decision.

Each field needs traceable evidence. If a decisive item is missing, the decision remains EVIDENCE_INSUFFICIENT_OPEN.

14. Lab and transfer

The lab is fully offline and synthetic. Eight fixtures model a baseline, same-content retag, writable-layer loss after replacement, named-volume persistence, bind-mount host coupling, a platform/manifest distinction, missing decisive evidence, and a changed-context transfer case.

No registry, credential, production system, or external network is used. The transfer case requires recomputing every state from changed evidence rather than copying the baseline diagnosis.

15. Sources, freshness, and claim boundaries

On 2026-09-19 the official OCI and Docker sources were rechecked. The OCI Image Spec still defines an image in terms of a manifest, optional index, filesystem layers, and configuration; descriptor digests remain content-reference/verification evidence; Docker still describes images as immutable/layered, runtime containers as having a separate writable layer, persistent storage via volumes/bind mounts/tmpfs, and networking as a runtime attachment concern.

These claims are tool/spec-sensitive. Review is due on 2026-10-17, with earlier requalification after material OCI Image Spec, Docker storage/network, or fixture changes.