Multi-Stage Builds, Minimal Runtime Images, Distroless Patterns, Debug Stages, and Build Separation: Configuration, Design Choices, and Tradeoffs

1. Start with runtime requirements, not a favorite base

The correct final base follows from an inventory: Does the process require a dynamic loader? Which native libraries? CA roots? Timezone or locale data? Name-service configuration? A writable temporary directory? A users database? A shell as part of the supported operational contract? FIPS-validated crypto? Vendor support? Once those requirements are explicit, image choice becomes an engineering decision rather than folklore.

2. Base-image decision table

Current Distroless docs explicitly suffix Debian 13 image names. Referencing the distribution family makes upgrades intentional instead of relying on a future moving default.

3. Static versus dynamic is a dependency-management choice

A static executable can be excellent for scratch because the binary carries the code it needs from its linked libraries. But “static” does not mean “no dependencies”: the program may still need certificates, timezone data, configuration, DNS behavior provided by the host/kernel, writable directories, or external services. Some ecosystems also intentionally rely on dynamic native libraries for compatibility, security updates, plugins, or vendor support.

A dynamically linked executable copied into scratch can fail even though the binary file exists. The kernel may report an execution error because the ELF interpreter/dynamic loader named by the binary is missing. This is a runtime-filesystem dependency failure, not a Docker daemon failure.

4. Distroless: narrow runtime, explicit debugging

Current Distroless Debian 13 static includes CA certificates, tzdata, a root passwd entry, and /tmp; base-nossl adds glibc; base adds glibc plus SSL runtime dependencies; cc adds libgcc-related runtime pieces. Choose the family matching the program rather than assuming all Distroless images are equivalent.

Production variants intentionally lack a shell. The project publishes debug and debug-nonroot variants that add a BusyBox shell for investigation. This maps directly to the chapter principle: diagnosability belongs in a deliberate debug identity, not in an undocumented hot patch of the release image.

5. Choose a debug strategy before the incident

The course favors the first two patterns for ordinary containerized applications. Host-namespace joining or privileged diagnostic containers are security-sensitive and belong in separately authorized labs, not this chapter's mandatory path.

6. COPY --from source identity is part of provenance

--from=build refers to a named stage in the same build definition. It is easy to audit because the producing stage is visible nearby. --from=nginx:tag or another external image is also valid Dockerfile syntax, but that external reference becomes a supply-chain input. Pin it by digest when the copied bytes must be reproducible.

Named contexts from Chapter 08 provide another option: the source can be supplied separately with --build-context. This can keep large or independently versioned inputs outside the main context, but their identity and trust still need evidence.

7. Least privilege crosses filesystem ownership and process identity

Setting a non-root USER is necessary but not sufficient. The copied executable, configuration, certificates, writable directories, and mounted volumes must have permissions compatible with that identity. A minimal image makes accidental assumptions visible because there may be no startup script running as root to repair permissions behind the scenes.

FROM scratch AS runtime
COPY --from=build --chown=65532:65532 /out/app /app
USER 65532:65532
ENTRYPOINT ["/app"]

If the application needs a writable directory, create/copy it deliberately or mount one with controlled ownership. Do not switch the process to root merely because a path was packaged incorrectly.

8. Smaller surface helps, but security evidence remains multidimensional

Removing compilers and package managers can reduce exploitable utilities, scanner noise, transfer size, and patch burden. Yet the application binary and its libraries still have vulnerabilities; base images and copied artifacts still need provenance; runtime Linux capabilities and seccomp/LSM controls still matter; and a signed image still needs vulnerability and runtime-health evaluation.

Therefore record at least: final digest, source/build identity, exact base digest, artifact checksum, runtime user, copied dependency list, scan result when a scanner is part of your environment, and the exception rationale for any additional tooling.

9. Worked decision: outbound-TLS Go service

Suppose a Go service is compiled with CGO_ENABLED=0, has no plugins, writes only to stdout, but calls public HTTPS APIs and needs timezone conversions. Plain scratch is insufficient unless you deliberately copy CA roots and timezone data. Current Distroless static-debian13 already includes CA certificates and tzdata, so it can be a strong candidate. A minimal distro is also defensible if your organization requires package-managed runtime inspection or a supported shell-based runbook.

The decision is justified by runtime dependencies and operating policy, not by one universal “best” base.

10. Decision exercise

Choose a base for each: (a) a static CLI-style service with no TLS/timezone needs; (b) a dynamically linked C++ service requiring libstdc++, CA roots, and no shell; (c) a vendor agent whose support procedure requires package-manager diagnostics. State the prerequisite evidence and a debugging strategy for each.

Knowledge check

Official references and version notes

• Docker multi-stage builds — named stages, COPY --from, stage reuse, and stopping at a specific target.
• Dockerfile reference — FROM, stage naming, COPY --from, USER, ENTRYPOINT, and current frontend semantics.
• Base images — choosing base images and creating minimal images with the reserved scratch base.
• Docker build best practices — small trusted bases, rebuilding, pinning, decoupling applications, and non-root considerations.
• docker buildx build — --target, --metadata-file, progress, output, and build-result evidence.
• docker image inspect — size and runtime configuration evidence.
• docker image history — image-history evidence and its limits.
• GoogleContainerTools/distroless — current Distroless image families, Debian 13 tags, nonroot/debug variants, no-shell behavior, and signature guidance.
• Distroless base image contents — static/base/base-nossl runtime contents such as CA certificates, tzdata, glibc, and libssl.
• Distroless support policy — current Debian-family support timelines.
• Docker Engine 29 release notes — current Engine baseline and bundled component updates.
• Buildx releases — current Buildx release history.
• BuildKit releases — current BuildKit and built-in Dockerfile frontend history.