While building Docker images, there are times when you might need to customize various aspects of the build process. This could involve choosing specific versions of software, enabling or disabling features, or adjusting other build-time configurations to suit your needs. This is where Docker build args come into the picture. 

In this blog post, we will learn what Docker build args are and how to use them. Let's get started! 

What are Docker Build Args

Docker build arguments, commonly referred to as "build args," are a Docker feature designed to pass variables exclusively during the Docker image's build process. 

Build args are particularly useful when you need to build Docker images that require specific configurations, but you want to avoid hardcoding those configurations in the Dockerfile. Note that Docker build args are not included in the final image and thus don't persist in containers created from that image.

You define build args in a Dockerfile using the ARG instruction. When you build the image using the docker build command, you can pass values for these args using the --build-arg flag. 

How to Use Docker Build Args

In this section, I’ll walk you through a hands-on example that will help you understand how to use build args in a Dockerfile and during the image build process.

Understanding the ARG instruction

In a Dockerfile, we define build args using the ARG instruction. This instruction is used to specify variables that can be passed to Docker during the build process. Its syntax is straightforward:

ARG <name>[=<default value>]

Here, <name> is the name of the variable you define, and you can optionally assign a default value.

Note that you can define multiple ARG instructions in your Dockerfile. Each ARG allows you to pass different variables during the build process.

Creating a sample Dockerfile

Start by launching your preferred code editor. Next, create a directory, and within the newly created directory, create a file named Dockerfile. Note that this Dockerfile mustn’t have an extension.

Within this Dockerfile, copy and paste the following code:

# Define the base image with a build arg for the version
ARG ALPINE_VERSION=3.16

FROM alpine:${ALPINE_VERSION}

# Another build arg for custom configuration
ARG CONFIG_OPTION

# Use the CONFIG_OPTION in some way inside the Dockerfile
RUN echo "Configuration option set to: ${CONFIG_OPTION}"

Want to learn how to build a Docker image with Dockerfile from scratch? Check out our blog post: How to Build a Docker Image With Dockerfile From Scratch

In this Dockerfile, we have two ARG instructions: ALPINE_VERSION with a default value of 3.16, and CONFIG_OPTION without a default value.

Note: In a Dockerfile, ARG is the only instruction that can be used before the FROM instruction for defining build arguments.

It’s important to understand that ARG instructions create zero-byte-sized layers. This means that ARG instructions don’t contribute any additional size to the image as they don't contain any file additions or changes. They’re essentially metadata layers that store the state of the build argument at that particular point in the Docker build process.

Building the image with build args

To build a Docker image and pass values for the build args (which we have defined using ARG instructions in the Dockerfile), we use the docker build command with the --build-arg flag, which has the following syntax:

--build-arg <arg_name>=<value>

Here, <arg_name> corresponds to the name of the argument as defined by the ARG instruction in the Dockerfile, and <value> is the value you wish to assign to this argument during the build.

It's important to remember that for every --build-arg parameter used in the docker build command, there must be a corresponding ARG instruction in the Dockerfile. This ensures that the build args you're trying to pass are explicitly declared and managed within the Dockerfile.

Considering our Dockerfile example, let's proceed to build a Docker image. Ensure you're in the directory containing the Dockerfile. Then, run the following command:

docker build --build-arg ALPINE_VERSION=latest --build-arg CONFIG_OPTION=some_value -t docker_buildargs_demo .

In this command:

• --build-arg ALPINE_VERSION=latest: Overrides the default Alpine version (3.16) in the Dockerfile with latest. 
• --build-arg CONFIG_OPTION=some_value: Provides a value (some_value) for CONFIG_OPTION. As CONFIG_OPTION is defined in the Dockerfile without a default value, it's necessary to assign a value here.
• -t docker_buildargs_demo: Tags the built image with the name docker_buildargs_demo.

After running the command above, the image build should finish within a few seconds, and you’ll see an output similar to this:

As highlighted above, the RUN command in the Dockerfile executed and echoed the value of CONFIG_OPTION during the build process.

Now run the following command: 

docker history docker_buildargs_demo

The docker history command is used to inspect the layers and the history of changes in a Docker image. It provides details about each layer, including its creation time, size, and the specific commands executed to create it. 

After running the above command, you’ll see an output similar to this: 

Since we used the value of CONFIG_OPTION inside a RUN command, which creates a new layer, we can see its value in the corresponding layer’s history.

The visibility of CONFIG_OPTION in the build history demonstrates an important point: even though ARG values are not present in the final image, they can be exposed in the intermediate layers. If an ARG value is used in Dockerfile commands that create a layer (like RUN), it becomes visible in the output of the docker history command. This is because such commands embed the ARG value in the layer they create. As a result, you should never use ARG instructions for storing sensitive data like passwords and API keys.

Conclusion

In this blog post, we learnt what Docker build args are and how to use them to customize various aspects of the Docker image build process.

Interested in learning more about Docker? Check out the following courses from KodeKloud:

• Docker for the Absolute Beginner: This course will help you understand Docker using lectures and demos. You’ll get a hands-on learning experience and coding exercises that will validate your Docker skills.  Additionally, assignments will challenge you to apply your skills in real-life scenarios.
• Docker Certified Associate Exam Course: This course covers all the required topics from the Docker Certified Associate Exam curriculum. The course offers several opportunities for practice and self-assessment. There are hundreds of research questions in multiple-choice format, practice tests at the end of each section, and multiple mock exams that closely resemble the actual exam pattern.