Description

In the past, we refused pull requests which were basically allowing to inject environment variables or such through the command line as it makes it too easy to write a Dockerfile which would only build assuming you know what it expects. We believe this would hinder repeatability of builds.

Nevertheless, there is a real need for build-time argument passing, one example which we often get being HTTP_PROXY. We believe Docker should have a predefined set of general purpose build-time variables it allows to override like this one, as well as a Dockerfile instruction allowing to define image-specific ones.

How to

The best description of the solution is described here #9176 (comment). However, we would still like to prioritize client-side build (#14298) before moving on to this feature.

To give a few more details:

• Introduce a new ARG Dockerfile instruction that defines a build-time argument. The instruction take the name of the argument, a default value (which can be empty), and an optional description.
• Introduce an internal list of builtin, Engine-provided, build arguments. In a first version, the set of predefined arguments will be HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, and NO_PROXY.
• Introduce a new --build-arg command-line flag to docker build that will receive argument values (e.g., docker build --build-arg HTTP_PROXY=http://...) in a similar way that docker run -e works today.
• Build-time arguments will not be persisted into the resulting image.
• Build-time arguments are injected in the environment of commands being RUN'ed as part of the build.
• Build-time arguments are available as substitution throughout the Dockerfile (for example, they can be used as part of an ENV instruction).

What's next

Ping @duglin for review.
Ping @mapuri: we'd really appreciate if you could close your original PR and submit a rebased version of it that implements the spec described here. Thanks again for your patience 👍

Tentatively adding this to the 1.9.0 milestone.