Docker’s “build-args” mechanism allows you to define environment variables that can be referenced in your file Dockerfile during image construction. Different from normal ENV Instructions, build arguments are not present in the final output image. They are intended for cases where you want to configure the build process instead of created containers.
Table of Contents
Define build arguments
You define build arguments in your Dockerfile use ARG Instructions:
ARG EXAMPLE_VAR ARG DEMO_VAR RUN echo $EXAMPLE_VAR
two arguments EXAMPLE_VAR and DEMO_VARare added to the build by the Dockerfile above.
You set the values of the available arguments using --build-arg flag for docker build. Repeat the flag multiple times to cover all of the arguments defined in yours Dockerfile:
docker build -t example-image:latest
--build-arg EXAMPLE_VAR=value1
--build-arg DEMO_VAR=value2
.
creating the sample Dockerfile This command outputs value1 to your terminal during build. That EXAMPLE_VAR Variable is provided with the value in the build environment value1. The value component of --build-arg flag is optional; If you omit it, the variable’s value is automatically selected in your local shell environment.
Because build arguments are not stored in the built image, you’ll see an empty string when you run it echo $EXAMPLE_VAR created in containers example-image:latest. Variables that running containers need to reference should be added using ENV instructions & --env or -e build flags.
Although not included in the final image, build arguments still affect Docker’s build cache. Changing the value of an argument between builds can cause cache misses for statements following the first a notice to the variable. The defining ARG statement is not responsible for cache invalidation.
FROM alpine:latest ARG EXAMPLE_VAR # Cache is not invalidated - arg hasn't been used RUN example-command # Build cache can't be used from this point onwards RUN echo $EXAMPLE_VAR
Default build arg values
That ARG A default value can be specified to be used if there is no match --build-arg Flag will be delivered:
ARG EXAMPLE_VAR=demo
Docker always prefers the value specified by the --build-arg mark if one is available. if it is missing EXAMPLE_VAR is set demo within the build environment. This reduces the number of flags you need to specify when building an image with rarely overridden arguments.
Where can Build Args be used?
Build arguments can be referenced in the Dockerfile directives that follow them. They work with most types of instruction, including RUN Commands run in the intermediate build containers. Arguments are referenced in the same way as environment variables, using the $EXAMPLE_VAR Syntax.
ARG Instructions are unique in that they significantly affect the build but can be used beforehand FROM Testify. Reference to build arguments within a is allowed FROM Directive that allows you to choose a different base image depending on the user’s configuration:
ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}
docker build -t my-app:latest --build-arg BASE_IMAGE_VERSION=debian .
Build arguments are available on the line on which they are defined. Each following statement can refer to the value of build arguments built over it in the Dockerfile. You got to Add ARG Instructions for any build arguments you will use. Referencing an argument before it’s defined – or using a --build-arg without corresponding ARG – returns an empty string.
Build arguments don’t work across build stages. Each phase acts as a new build with its own set of build arguments. ARG Statements contained in earlier phases have no effect on later ones unless they are repeated in each phase:
FROM php:latest ARG BUILD_VERSION FROM composer:latest ARG BUILD_VERSION
Both stages explicitly define the BUILD_VERSION arg is the value set with --build-arg is delivered to everyone.
Build phase considerations also apply when using ARG before a FROM Instruction. These arguments exist outside of each build phase; they are shared by everyone FROM instructions, which, however, cannot be referenced by the following instructions. If you want to reuse one FROM-level build arg within a level, repeat it ARG Instruction to collect its value:
# Only applies to FROM instructions
ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}
# Reference the outer build argument
ARG BASE_IMAGE_VERSION
# Works as expected
RUN echo $BASE_IMAGE_VERSION
Aside from these specific concerns, arguments behave similarly to environment variables in all other respects. You can overwrite their values with ARG and ENV statements, interpolate them into strings and use them in form expansion expressions ${EXAMPLE_VAR:-demo}. That selects demo than the value if the EXAMPLE_VAR Variable is not set.
Predefined build arguments
Docker supports some build arguments by default, even if you don’t include them ARG Instructions in your Dockerfile. she relate to proxy settings and work whenever they correspond --build-arg flag is used. The variables are also excluded docker history Output to avoid revealing potentially sensitive details they are intended for – more on this command and its implications below.
Builds handled by the BuildKit backend can also access several other predefined build arguments. These are supplied with automatically fed values. The list contains TARGETOS, TARGETARCH, TARGETPLATFORMand BUILDOS, BUILDARCHand BUILDPLATFORM, among several others. The variables describe characteristics of the build environment and platform targeted by the new image.
When should build arguments be used?
Build arguments can be used to inject configurations into Docker image builds. They are a way to dynamically change the final image without writing multiple Dockerfiles.
You can use this mechanism to change a build’s base image and change the commands that it runs RUN Instructions and provide user-changeable settings that expose image adjustment options. Build arguments make sense for most values that are only used during the build process and that you don’t want to hardcode in your Dockerfile.
There are some situations where alternative approaches should be used. Build arguments, while convenient, are not ideal for secrets such as authentication tokens and keys. There ARG is a Dockerfile directive, variables and their values are visible when examining an image with the docker history Command. Therefore, anyone with access to your image can see the keys used during the build.
Credentials used to authenticate your build process to package registrations and source control repos are best provided as a BuildKit building secrets. These are designed to handle sensitive information and are included in the build environment as files rather than becoming image instructions.
summary
Build arguments allow you to configure Docker image builds at build time using a combination of Dockerfile directives and command-line arguments. Unlike environment variables, build arguments are not accessible for running containers, although they are still visible in the image’s layer history.
A build argument is the right choice for non-sensitive, user-customizable settings that affect your build process. Use an environment variable instead if you want the value to be available in the final image. BuildKit secrets are a better third option for any valuable data your build needs to access.
This article was previously published on Source link
