Docker / Images and container fundamentals / Lesson 2
Images, layers, tags, and content identity
Trace an image reference to its content and distinguish image history from durable application data.
On this page
Lesson goals
- Explain layers, manifests, tags, and digests.
- Interpret image inspection without inventing fixed ids or sizes.
Layers record filesystem changes
An image filesystem is assembled from ordered, read-only layer changes. Instructions such as COPY and RUN can add content to later layers, while metadata instructions configure how containers start. A container receives a separate writable layer. Removing a file in a later build step hides it from the final filesystem view but may leave its earlier bytes in image history. Never copy credentials and assume a later deletion erases their exposure.
A tag is a movable name
The reference python:3.13-slim selects a repository and tag, not permanent bytes. A registry can publish updated content under the same tag. A digest identifies content cryptographically; a multi-platform index digest can reference several platform-specific manifests rather than one root filesystem. Readable tags help people understand intent, while reviewed digests help identify a release exactly. Record both purpose and resolved identity in release evidence.
docker image inspect python:3.13-slim
docker buildx imagetools inspect python:3.13-slimThe local inspection describes an already available image in an authorized engine. imagetools inspects registry-side manifests and may contact a registry. Their digest and platform fields are environment-dependent, so this lesson does not fabricate values or claim either command was executed. A local tag can remain older than the registry's current tag.
Read history as provenance evidence, not a secret vault
Image history helps explain instruction sequence and approximate layer contributions, but it is not complete source provenance or an application audit log. Build arguments and command text can reveal sensitive inputs. A small final image is useful for transfer and maintenance, yet size alone does not prove safety. Review base origin, package selection, runtime privileges, and actual reachable vulnerabilities alongside image size.
docker image history --no-trunc parcel-api:lab
docker image inspect parcel-api:lab --format '{{json .Config}}'These read-only queries target an existing synthetic image. History explains build steps; Config includes defaults such as command, user, and exposed ports. They do not prove which overrides an existing container received. Treat untruncated history as potentially sensitive and share only necessary redacted fields.
Rebuilding is different from restarting
Restarting an existing container starts its current configuration again; it does not rebuild the image, fetch a changed tag, or apply a new Dockerfile. Building produces new image content, and adopting it requires a reviewed container replacement. Separate source revision, image reference, and running container id when diagnosing an update. Otherwise a correct new image can exist locally while an older container continues serving traffic.
Retention is a data ownership decision
Image layers, build cache, container writable layers, and persistent volumes have different lifecycles. An unused image is not necessarily unwanted: it may be a rollback artifact or release evidence. Broad cleanup commands can affect unrelated projects and should never be a default troubleshooting response. Define retention owners and storage budgets, inspect what consumes space, and remove only specifically reviewed artifacts through the environment's operational process.
Common errors and fixes
pull access denied.
- Why it happens
- The reference may name the wrong repository, require authentication, or be inaccessible from the chosen registry.
- How to fix it
- Verify the exact repository and permitted identity before changing registry settings.
- Prevent it next time
- Record trusted registries and avoid guessing similarly named images.
The same tag yields different bytes on another day.
- Why it happens
- Tags are mutable and the publisher updated the referenced content.
- How to fix it
- Resolve and approve a digest for release identity while retaining an update policy.
- Prevent it next time
- Store resolved image identity with source and build metadata.
Deleted credentials remain recoverable from an earlier layer.
- Why it happens
- A secret was copied into image content before a later deletion.
- How to fix it
- Rotate exposed credentials and rebuild without ever copying them into layers.
- Prevent it next time
- Use build secret mounts and exclude sensitive files from context.
Check your understanding
1. Does a container restart adopt a newly published python tag?
Show worked solution
No. The existing container retains its image identity and runtime configuration. A controlled update resolves or pulls the intended content, builds the application where needed, and replaces the container after validation. Keeping the same friendly name does not make old and new container identities equivalent.
2. Why record a platform when recording an image digest?
Show worked solution
A reference may resolve to a multi-platform index whose children describe different architectures. Record whether the digest identifies an index or a single manifest and which platform was selected. That makes a later runtime mismatch diagnosable without assuming every machine received identical platform-specific filesystem content.
Key takeaways
- Use tags for readable intent and reviewed digests for content identity.
- Layer history and runtime state answer different questions.