Image slimming: multi-stage, distroless, and layers that pull in seconds

Multi-stage: build heavy, ship light

The core technique is the multi-stage build: one stage holds the heavyweight toolchain, the final stage holds only the artifact. Only the last stage becomes the image; everything in the build stage — compilers, caches, dev dependencies — is discarded.

# ---- build stage: heavy, never shipped ----
FROM golang:1.23 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download                 # cached unless go.mod/go.sum change
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

# ---- final stage: tiny, shipped ----
FROM gcr.io/distroless/static-debian12   # ~2 MB base: no shell, no package manager
COPY --from=build /app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

The final image is the distroless base (~2 MB) plus the binary — for a static Go binary, ~25 MB total versus 1.2 GB for the naive single-stage build off golang:1.23. That size is not a vanity metric; it is paid back on every operation. A pull on a cold node drops from ~90 s to ~2 s, which directly shortens autoscaler reaction time and rollout duration. The registry stores and transfers a fraction of the bytes. And the attack surface collapses: distroless ships no shell, no package manager, and no OS utilities, so a compromised process cannot sh, curl, apt-get, or pivot through libc tools — and the CVE scanner reports near-zero findings because there are almost no OS packages to have vulnerabilities. For a truly static binary you can even use FROM scratch (empty base), shipping literally just the binary; distroless is the pragmatic middle ground because it adds CA certificates, /etc/passwd, and timezone data that scratch lacks.

Layer ordering: cache the slow steps

You have a 25 MB final image — but if you order the Dockerfile instructions wrong, every code change still triggers a multi-minute dependency reinstall. The image size is paid at pull time; the layer order is paid at build time, on every commit.

Image layers are content-addressed and cached: a layer is reused only if its instruction and all preceding layers are unchanged. Order instructions from least- to most-frequently-changing so a one-line code edit doesn’t bust the dependency-install layer. The single highest-leverage rule is copy and install dependencies before copying source code.

# GOOD — dependency layer survives source edits
COPY package.json package-lock.json ./
RUN npm ci                # cached until package files change
COPY . .                  # source changes invalidate only from here down
RUN npm run build

# BAD — every source edit re-runs npm ci (minutes)
COPY . .
RUN npm ci                # any file change busts this; full reinstall every build

In the bad order, COPY . . lands before npm ci, so editing one line of source changes the build context, invalidates that COPY layer, and forces a full dependency reinstall — turning a 5-second incremental build into a multi-minute one. In the good order the dependency install sits on a stable layer keyed only by the lockfiles, so it is reused across every source-only change. Two more layer disciplines matter: a .dockerignore that excludes node_modules, .git, and test fixtures keeps junk out of the build context (smaller, faster, and it prevents a stale local node_modules from leaking in); and combining related RUN steps with cleanup in the same layer (apt-get install ... && rm -rf /var/lib/apt/lists/*) matters because removing files in a later layer does not shrink the image — the bytes are already committed in the earlier layer and only masked, not deleted. Layer count is also a real number: each layer is a separate tar fetched and extracted, so dozens of tiny RUN lines slow pulls; consolidate, but not so aggressively that you destroy cache reuse.