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:
- Deleting files in a later Dockerfile step doesn't shrink the image.
- 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. latestis 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).
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.