Opscraft
Docker · Lesson 2 of 11 · 3 min read

Images, layers and registries

Layers and the union filesystem

An image is an ordered stack of read-only layers plus a JSON config (env vars, entrypoint, user, exposed ports, labels). Each layer is a tarball of filesystem changes. The overlay2 storage driver stacks them:

  • lowerdir — the image layers (read-only, shared between all containers using them),
  • upperdir — the container's thin writable layer,
  • merged — the combined view the container sees.

Writing to a file that exists in a lower layer triggers copy-up: the whole file is copied into the writable layer first. Deleting a file from a lower layer creates a whiteout marker — the bytes still exist in the lower layer. Two consequences:

Enlarge diagramcontainer A: writable layercontainer B: writable layerCOPY app.jarRUN apt-get install …FROM eclipse-temurin:21-jreDeleting a file in a later step only hides it (a "whiteout"); the bytes stay in the earlier layer. So RUN rm does notshrink the image, and secrets copied in stay readable.upperdirlowerdir(shared)
Figure 1. An image is a stack of read-only layers. Each container adds a thin writable layer on top; overlay2 merges them into one view.
Swipe sideways to see all of it, or tap to open it full screen.
  1. Deleting files in a later Dockerfile step doesn't shrink the image.
  2. Heavy write workloads (databases) shouldn't write to the container layer — use volumes.

Because layers are shared, 50 containers from the same image use the image's disk space once.

Tags, digests and manifests

  • A tag (myapp:1.4.2, myapp:latest) is a mutable pointer. Someone can push a different image under the same tag.
  • A digest (myapp@sha256:9f86...) is the content hash of the manifest — immutable. Pulling by digest guarantees exactly the same bits.
  • latest is just the default tag name, not "the newest". Never deploy it.

A manifest lists the config and layer digests. A manifest list / image index points to per-platform manifests (linux/amd64, linux/arm64), so docker pull gets the right architecture automatically — important when you move EKS nodes to Graviton (arm64).

Enlarge diagramorders:latestmutable tagorders:3f9c2a1immutable by conventionmanifest@sha256:9f86…linux/amd64layerslinux/arm64GravitontodayA multi-arch image index points at one manifest per platform; docker pull picks the right one.
Figure 2. A tag is a movable label; a digest is the content hash and never changes. Deploy by SHA tag or digest, not by latest.
Swipe sideways to see all of it, or tap to open it full screen.
docker pull nginx:1.27
docker images --digests
docker inspect --format '{{index .RepoDigests 0}}' nginx:1.27
docker manifest inspect nginx:1.27      # see platforms
docker history --no-trunc myapp:1.4.2   # layers and the commands that made them
docker image inspect myapp:1.4.2 | jq '.[0].Config'

Registries and naming

An image reference is registry/repository:tag. Without a registry it defaults to Docker Hub (docker.io/library/nginx). ECR references look like 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders:3f9c2a1.

Docker Hub enforces pull rate limits for anonymous and free users — a real cause of CI and node failures. Mitigate with authenticated pulls, an ECR pull-through cache, or mirroring base images into your own registry.