--build-arg help and validation feature

[abacaphiliac]

hi Team,

thank you for a very useful tool.

i believe this is a feature request. i checked for duplicates in open Issues and PRs.

it would be great if docker build could enumerate the available build-arg list, either from docker build --help (e.g. in an Arg section separate from the Options section) or through some other help-like sub-command.

building on that idea, it would also be useful if Dockerfile authors could include build-arg validation so that build param types and values could be asserted before kicking off lengthy run steps.

thank you for your consideration.

[abacaphiliac]

for example:

Dockerfile:

FROM ubuntu:14.04
ARG FOO
ENV FOO=${FOO:-BAR}
RUN echo $FOO

docker build --help (Note the new Arg section):

08:16 $ docker build --help

Usage:	docker build [OPTIONS] PATH | URL | -

Build an image from a Dockerfile

Options:
      --add-host list              Add a custom host-to-IP mapping (host:ip)
      --build-arg list             Set build-time variables
      --cache-from stringSlice     Images to consider as cache sources
      --cgroup-parent string       Optional parent cgroup for the container
      --compress                   Compress the build context using gzip
      --cpu-period int             Limit the CPU CFS (Completely Fair Scheduler) period
      --cpu-quota int              Limit the CPU CFS (Completely Fair Scheduler) quota
  -c, --cpu-shares int             CPU shares (relative weight)
      --cpuset-cpus string         CPUs in which to allow execution (0-3, 0,1)
      --cpuset-mems string         MEMs in which to allow execution (0-3, 0,1)
      --disable-content-trust      Skip image verification (default true)
  -f, --file string                Name of the Dockerfile (Default is 'PATH/Dockerfile')
      --force-rm                   Always remove intermediate containers
      --help                       Print usage
      --iidfile string             Write the image ID to the file
      --isolation string           Container isolation technology
      --label list                 Set metadata for an image
  -m, --memory bytes               Memory limit
      --memory-swap bytes          Swap limit equal to memory plus swap: '-1' to enable unlimited swap
      --network string             Set the networking mode for the RUN instructions during build (default "default")
      --no-cache                   Do not use cache when building the image
      --pull                       Always attempt to pull a newer version of the image
  -q, --quiet                      Suppress the build output and print image ID on success
      --rm                         Remove intermediate containers after a successful build (default true)
      --security-opt stringSlice   Security options
      --shm-size bytes             Size of /dev/shm
      --squash                     Squash newly built layers into a single new layer
  -t, --tag list                   Name and optionally a tag in the 'name:tag' format
      --target string              Set the target build stage to build.
      --ulimit ulimit              Ulimit options (default [])

Args:
      --FOO

ideally i could get additional info about the build-arg from help, or receive validation errors if i use unacceptable values, e.g.

08:16 $ docker build --help
Options:
      --add-host list              Add a custom host-to-IP mapping (host:ip)
      ...

Args:
      --FOO                        String, default: "Bar"

Sample invalid execution should exit non-zero because an integer was used instead of a string.
docker build -t Foo --build-arg FOO=1234 .

[dnephin]

I agree these would be nice features. Documenting args reminds me of a feature I've wanted to allow the Dockerfile to declare required volumes and usage help text.

Showing all available --target options for a multi-stage build would also be valuable.

Unfortunately I don't see an easy way to implement this. The problem with your example is that it assumes the context is ., and the Dockerfile is in the root of the context. That might be a common case but it's not a safe assumption.

I don't think it's right to mix build flags with information about the Dockerfile, so we'd want some other flag (not --help). A subcommand of build would be nice but we already have positional args on build so that wouldn't be backwards compatible.

The command line would need to be something like docker build [-f Dockerfile] --info CONTEXT.

Another problem is that the Dockerfile is not parsed by the client. Personally I think it should be (it would remove the need for some of the untar/re-tar hacks we have right now), but not everyone agrees. So either we add API endpoints to return details about a Dockerfile, or we move the Dockerfile parser to the client, which is not a small change.

cc @tonistiigi

[tonistiigi]

https://github.com/moby/buildkit returns a build layout/trace before executing the build, for example showing what parts will match the cache. Possibly Dockerfile frontend could extend that and add the ARG and other Dockerfile specific sections. There is no need to do it on the client side, it is just a property when invoking the build. My view of the problem is that currently Dockerfile is parsed on the client side and that is the reason for these tar hacks you mention.

[tonistiigi]

There are cases where you actually can't do it on the client. For example, if env defined in a FROM image is used as a value for ARG.

[kevingentile]

Possibly related, If you are attempting to pass a --build-arg FOO=asdf through the CLI but missing ARG FOO in Dockerfile, the build-arg is not included in the build run. I would expect at least a warning that the build-arg flag is being ignored.
Warning: ARG FOO is not defined in Dockerfile

Docker version 20.10.5, build 55c4c88

[thaJeztah]

Possibly related, If you are attempting to pass a --build-arg FOO=asdf through the CLI but missing ARG FOO in Dockerfile, the build-arg is not included in the build run. I would expect at least a warning that the build-arg flag is being ignored.
Warning: ARG FOO is not defined in Dockerfile

Docker version 20.10.5, build 55c4c88

Hmm... looks like that's something to be addressed in BuildKit. The "classic" builder printed a warning, but looks like buildkit doesn't;

Without BuildKit:

DOCKER_BUILDKIT=0 docker build --build-arg FOO=bar -<<EOF
FROM busybox
RUN echo hello
EOF

Sending build context to Docker daemon  2.048kB
Step 1/2 : FROM busybox
 ---> 388056c9a683
Step 2/2 : RUN echo hello
 ---> Running in 0ff64e1edd4b
hello
Removing intermediate container 0ff64e1edd4b
 ---> 26859e806085
[Warning] One or more build-args [FOO] were not consumed
Successfully built 26859e806085

With BuildKit:

DOCKER_BUILDKIT=1 docker build --build-arg FOO=bar -<<EOF
FROM busybox
RUN echo hello
EOF

[+] Building 0.5s (6/6) FINISHED
 => [internal] load build definition from Dockerfile                                                                                                                                                   0.1s
 => => transferring dockerfile: 70B                                                                                                                                                                    0.0s
 => [internal] load .dockerignore                                                                                                                                                                      0.0s
 => => transferring context: 2B                                                                                                                                                                        0.0s
 => [internal] load metadata for docker.io/library/busybox:latest                                                                                                                                      0.0s
 => CACHED [1/2] FROM docker.io/library/busybox                                                                                                                                                        0.0s
 => [2/2] RUN echo hello                                                                                                                                                                               0.3s
 => exporting to image                                                                                                                                                                                 0.0s
 => => exporting layers                                                                                                                                                                                0.0s
 => => writing image sha256:af09f7baeb292afd37bf948398584d8d8299ede11aae4bf0654f038e082001fa

[thaJeztah]

I opened moby/buildkit#2128

[tonistiigi]

We have added --print outline and --print targets https://www.docker.com/blog/highlights-buildkit-v0-11-release/

[thaJeztah]

Yes, I think this ticket can be closed; there may still be some improvements to make (which can be reported in https://github.com/docker/buildx), but we now have --call (previously named --print);l

docker buildx build --call outline .
...
TARGET: binary

BUILD ARG               VALUE    DESCRIPTION
BASE_VARIANT            alpine
ALPINE_VERSION          3.21
GO_VERSION              1.23.8
XX_VERSION              1.6.1
GOVERSIONINFO_VERSION   v1.4.1
GO_LINKMODE             static   defines if static or dynamic binary should be produced
GO_BUILDTAGS                     defines additional build tags
GO_STRIP                         strips debugging symbols if set
CGO_ENABLED                      manually sets if cgo is used
VERSION                          sets the version for the produced binary
PACKAGER_NAME                    sets the company that produced the windows binary


docker buildx build --call targets .
...
TARGET            DESCRIPTION
xx
build-base-alpine
build-alpine
build-base-debian
build-debian
goversioninfo
gotestsum
build
test
test-coverage
build-plugins
e2e-base-alpine
e2e-base-debian
buildx
compose
e2e
dev
plugins
bin-image-linux
bin-image-darwin
bin-image-windows
bin-image
binary (default)