How do you make the image referenced by a Dockerfile's FROM instruction configurable at build time, and what is the scoping rule for an ARG declared before the first FROM?

## The mechanism A Dockerfile's FROM instruction accepts variable interpolation, but only from build arguments that exist before any stage begins. That is why the pattern is: ``` ARG BASE_IMAGE=debian:bookworm-slim FROM ${BASE_IMAGE} ``` At build time, docker build --build-arg BASE_IMAGE=gcr.io/distroless/base-debian12 substitutes the value. Providing a default is good practice so the Dockerfile still builds with no arguments and so readers can see the intended base. ## The scoping rule The Dockerfile grammar defines a small region before the first FROM, sometimes called the global or pre-FROM scope. ARG is the only instruction allowed there (aside from comments, directives such as syntax, and additional ARGs). Values declared there are consumed by FROM lines. Crucially, they do not automatically leak into build stages. After a FROM, you are inside a stage with its own argument scope, and referencing ${BASE_IMAGE} in a RUN there yields an empty string. The fix is to re-declare it inside the stage with a bare ARG: ``` ARG VERSION=1.2.3 FROM alpine:3.20 ARG VERSION RUN echo "building $VERSION" ``` The bare ARG inherits the outer value rather than resetting it; adding a default in the inner declaration would override the outer value when none is supplied. This same rule applies per stage in a multi-stage build: each stage that needs the value re-declares it. ## Predefined args BuildKit supplies platform args automatically in the pre-FROM scope: BUILDPLATFORM, BUILDOS, BUILDARCH (the machine performing the build) and TARGETPLATFORM, TARGETOS, TARGETARCH, TARGETVARIANT (the platform being produced). They can be used directly in FROM lines, which is the basis of cross-compiling multi-platform builds: ``` FROM --platform=$BUILDPLATFORM golang:1.23 AS build ARG TARGETOS TARGETARCH RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app . ``` Note the re-declaration inside the stage, exactly as with user-defined args. Proxy variables (HTTP_PROXY, NO_PROXY and lowercase forms) are also predefined and are excluded from image history. ## Practical uses - **Variant builds from one Dockerfile.** A BASE_IMAGE arg lets CI produce a distroless production image and a busybox-based debug image with identical application layers, which is a common answer to the "how do you debug a shell-less image" problem. - **Pinning per environment.** Some organisations mirror approved bases into an internal registry; a REGISTRY or BASE_IMAGE arg lets the same Dockerfile build from the public base locally and the mirrored, digest-pinned base in CI. - **Version matrices.** Building the same service against several runtime versions (for example JDK 21 and 25) to test compatibility. ## Cautions Build args are not secrets. Values passed with --build-arg are recorded in the image config and visible via docker history, and they are not the mechanism for credentials; BuildKit's --mount=type=secret exists for that. Parameterised bases also weaken reproducibility. If the default in the Dockerfile and the value CI actually passes diverge, a local build reproduces something different from production. Keep the CI value in a checked-in file (a Makefile, a compose file, a workflow) rather than in a person's shell history, and prefer a digest-pinned value for release builds. Finally, cache behaviour follows the argument: changing BASE_IMAGE changes the base layers, so the whole stage rebuilds. That is correct but worth expecting, particularly when a matrix build alternates values and each variant maintains its own cache lineage.