Part 2 · 1 chapters · ~8 min

Overlay Filesystems

Union mounts and overlayfs (lowerdir, upperdir, workdir, merged), copy-up and whiteouts, image layers as tarballs, content addressing by digest, layer caching in builds and why instruction order matters, multi-stage builds, volumes and bind mounts, and storage drivers.

Layers by hand, then in a Dockerfile

code

# Linux only: build a merged view from two read-only layers and a writable one
mkdir -p lower1 lower2 upper work merged
echo base > lower1/a.txt; echo app > lower2/b.txt
sudo mount -t overlay overlay -o lowerdir=lower2:lower1,upperdir=upper,workdir=work merged
echo changed > merged/a.txt          # copy-up: upper/a.txt now exists; lower1/a.txt untouched
rm merged/b.txt                      # whiteout: upper/b.txt is a 0:0 character device

code

# Dockerfile: order instructions from least to most frequently changed, so layers cache
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./      # changes rarely → npm ci layer is reused
RUN npm ci
COPY . .                                    # changes every commit
RUN npm run build

FROM gcr.io/distroless/nodejs22-debian12   # multi-stage: no compilers, no shell, small attack surface
COPY --from=build /app/dist /app/dist
COPY --from=build /app/node_modules /app/node_modules
CMD ["/app/dist/server.js"]

OVERLAYFS: HOW IMAGE LAYERS BECOME A ROOT FS

read-only layers, one writable layer, one merged view

swipe the figure sideways, or tap expand for full screen

1/4

layers

Each Dockerfile instruction that changes files produces a read-only layer, identified by the digest of its contents. Images share layers on disk.

content-addressed layersshared between images