[ad_1]
Docker’s “construct argument” mechanism allows you to define environment variables that can be referenced in your Dockerfile during imaging. Unlike regular ENV instructions, the build arguments are not present within the final output image. They are for cases where you want to configure the build process instead of the created containers.
Defining build arguments
You define construction arguments within your Dockerfile wearing ARG instructions:
ARG EXAMPLE_VAR ARG DEMO_VAR RUN echo $EXAMPLE_VAR
two arguments, EXAMPLE_VAR Y DEMO_VARthey are added to the build using the above Dockerfile.
Sets the values of the arguments available through the --build-arg flag for docker build. Repeat the flag several times to cover all the arguments defined in its Dockerfile:
docker build -t example-image:latest
--build-arg EXAMPLE_VAR=value1
--build-arg DEMO_VAR=value2
.
Building the sample Dockerfile using this command will issue value1 to your terminal during compilation. the EXAMPLE_VAR the variable is available in the build environment with the value value1. The value component of --build-arg the flag is optional; omitting it will automatically select the value of the variable in your local shell environment.
Since the build arguments are not preserved in the built image, you will see an empty string when running echo $EXAMPLE_VAR inside containers created from example-image:latest. Variables that should be referenced by running containers should be added using ENV instructions and --env either -e build flags.
Although not in the final image, build arguments still affect the Docker build cache. Changing the value of an argument between builds can cause cache misses for statements that follow the first reference to variable. the definition 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 argument values
the ARG The statement can be given a default value to use when there is no match --build-arg flag is supplied:
ARG EXAMPLE_VAR=demo
Docker will always prefer the value given by the --build-arg check when one is available. If missing, EXAMPLE_VAR will be set to demo within the built environment. This reduces the number of flags you have to supply when creating an image with arguments that are rarely overridden.
Where can compiler arguments be used?
Build arguments can be referenced in the Dockerfile instructions that follow them. They work with most types of instruction, including RUN commands executed on 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 materially affect construction, but can be used before FROM statements. It is allowed to refer to compiler arguments within a FROM statement, allowing you to select a different base image depending on user settings:
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 .
Compiler arguments are available from the line in which they are defined. Any following statements can reference the value of the build arguments created above in the Dockerfile. You have to add ARG instructions for all the compiler arguments it will use. Referencing an argument before it has been defined, or using a --build-arg without corresponding ARG – will return an empty string.
Build arguments don’t work in build stages. Each stage acts as a new build with its own set of build arguments. ARG instructions included in earlier stages have no effect on later ones unless they are repeated within each stage:
FROM php:latest ARG BUILD_VERSION FROM composer:latest ARG BUILD_VERSION
Both stages explicitly define the BUILD_VERSION arg so the value set with --build-arg will be delivered to each.
Build-stage considerations also apply when you use ARG prior to FROM instruction. These arguments exist outside of any stage of construction; are shared by all FROM but they cannot be referenced by following the instructions. If you want to reuse a FROM-level build arg inside a stage, repeat the ARG statement to extract 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
These special concerns aside, arguments behave similarly to environment variables in all other respects. You can override their values using ARG Y ENV statements, interpolate them into strings, and use them in expansion expressions of the form ${EXAMPLE_VAR:-demo}. This selects demo as the value when the EXAMPLE_VAR the variable is not set.
Predefined build arguments
Docker supports some build arguments by default, even if you don’t include their ARG instructions in your Dockerfile. They are related to proxy settings and work as long as their corresponding --build-arg flag is used. Variables are also excluded from docker history output to avoid revealing the potentially sensitive details for which they are intended; More information on this command and its implications below.
Builds handled by the BuildKit backend can also access various other predefined build arguments. These are supplied with automatically injected values. The list includes TARGETOS, TARGETARCH, TARGETPLATFORMY BUILDOS, BUILDARCHY BUILDPLATFORM, among several others. The variables describe the characteristics of the build environment and the platform that the new image targets.
When to use compiler arguments?
Build arguments can be used to inject configuration into Docker image builds. They are a way to dynamically modify the final image without writing multiple Dockerfiles.
You can use this mechanism to modify the base image of a build, change the commands it runs RUN instructions and provides user-changeable settings that expose image customization 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. While convenient, compiler arguments are not ideal for secret data such as tokens and authentication keys. Because ARG is a Dockerfile instruction, the variables and their values are visible when inspecting an image with the docker history domain. Therefore, anyone with access to your image can see the keys used during the build.
The credentials used to authenticate your build process to package logs and source control repositories are best provided as BuildKit build secrets. These are designed to handle sensitive information and are mounted as files in the build environment, rather than being converted to image instructions.
Summary
Build arguments allow you to configure Docker image builds using a combination of Dockerfile statements and command-line arguments at build time. Unlike environment variables, build arguments cannot be accessed by running containers, although they are still visible in the image’s layer history.
A build argument is the correct choice for non-sensitive user-customizable settings that affect your build process. Use an environment variable instead when you want to expose the value in the final image. BuildKit secrets are a better third option for any valuable data your build needs to access.
[ad_2]
