How to use docker buildx use command to switch builder instances

Introduction

In this lab, you will learn how to manage and switch between different Docker builder instances using the docker buildx use command. We will begin by creating multiple builder instances to have options for building Docker images.

Following the creation of these instances, you will learn how to list all available builder instances to view their details and status. The core of this lab will then focus on using the docker buildx use command to switch to a specific builder instance for your build operations. Finally, you will explore how to set a builder as the default for your current context and how to configure a builder to persist context changes.

Skills Graph

Create multiple builder instances

In this step, we will learn how to create multiple builder instances using Docker. Builder instances are used to build Docker images. By default, Docker uses a single builder instance. However, you can create multiple builder instances to improve build performance or to use different build configurations.

First, let's check the current builder instances.

docker buildx ls

You should see a default builder instance. Now, let's create a new builder instance named mybuilder1.

docker buildx create --name mybuilder1

This command creates a new builder instance. You can verify that the new instance has been created by listing the builder instances again.

docker buildx ls

You should now see both the default builder and mybuilder1.

Let's create another builder instance named mybuilder2.

docker buildx create --name mybuilder2

Again, verify the creation of the new instance.

docker buildx ls

You should now see the default builder, mybuilder1, and mybuilder2.

List available builder instances

In the previous step, we created multiple builder instances. In this step, we will focus on listing these available builder instances to see their status and details.

The command to list builder instances is docker buildx ls. This command provides information about all the builder instances that are available on your system.

Let's execute the command again to see the builder instances we created in the previous step.

docker buildx ls

The output will show a table with columns like NAME, DRIVER, ENDPOINT, STATUS, and BUILDER.

• NAME: The name of the builder instance.
• DRIVER: The driver used by the builder instance (e.g., docker-container).
• ENDPOINT: The endpoint the builder is connected to.
• STATUS: The current status of the builder instance (e.g., running, stopped).
• BUILDER: Indicates if this is the current builder being used.

You should see the default builder, mybuilder1, and mybuilder2 listed in the output. The STATUS column for the builders you created should show running if they were started automatically, or stopped if not.

This command is useful for checking which builders are available and their current state before switching or using them for building images.

Switch to a specific builder instance

In this step, we will learn how to switch to a specific builder instance. When you have multiple builder instances, you can choose which one to use for building your Docker images.

To switch to a specific builder instance, you use the docker buildx use command followed by the name of the builder instance.

Let's switch to the mybuilder1 instance that we created in the previous steps.

docker buildx use mybuilder1

After executing this command, the mybuilder1 instance will be the active builder for your current Docker context.

You can verify which builder is currently active by listing the builder instances again. The active builder will be marked with an asterisk (*) in the BUILDER column.

docker buildx ls

You should see an asterisk next to mybuilder1 in the output, indicating that it is the currently active builder.

Now, let's switch to the mybuilder2 instance.

docker buildx use mybuilder2

Verify that mybuilder2 is now the active builder.

docker buildx ls

You should see the asterisk next to mybuilder2.

Switching between builder instances allows you to easily utilize different build environments or configurations as needed.

Set a builder as default for the current context

In the previous step, we learned how to switch to a specific builder instance for the current session. In this step, we will learn how to set a builder instance as the default for the current Docker context. This means that whenever you use Docker commands within this context, the specified builder will be used automatically.

To set a builder as the default for the current context, you use the docker buildx use command with the --default flag, followed by the name of the builder instance.

Let's set mybuilder1 as the default builder for the current context.

docker buildx use --default mybuilder1

After executing this command, mybuilder1 will be the default builder for this context.

You can verify this by listing the builder instances. The default builder will be marked with an asterisk (*) and also indicated as default in the output.

docker buildx ls

You should see mybuilder1 marked as both the active builder (with *) and the default builder.

Now, let's set mybuilder2 as the default builder.

docker buildx use --default mybuilder2

Verify that mybuilder2 is now the default builder.

docker buildx ls

You should see mybuilder2 marked as both active and default.

Setting a default builder is useful when you consistently want to use a specific builder for your projects within a particular Docker context.

Set a builder to persist context changes

In the previous steps, we learned how to switch to a builder and set a default builder for the current context. However, these changes might not persist across different terminal sessions or system reboots depending on your Docker configuration. In this step, we will explore how to ensure that your chosen builder remains the default even after closing and reopening your terminal or restarting the Docker daemon.

The docker buildx use --default command sets the default builder for the current Docker context. This setting is usually stored in the Docker configuration file. To ensure this change persists, you typically don't need an extra command beyond setting the default. The --default flag is designed to make the change persistent for that specific context.

Let's re-confirm that mybuilder2 is set as the default builder.

docker buildx ls

You should still see mybuilder2 marked as the default builder.

The persistence of this setting relies on Docker's configuration management. When you use docker buildx use --default, Docker updates its configuration to reflect this choice for the active context. This configuration is loaded when Docker starts, ensuring that your preferred builder is used by default.

While there isn't a separate command specifically for "persisting" the change beyond using --default, understanding that the --default flag handles this persistence within the Docker context is important.

To truly test persistence, you would typically restart the Docker daemon or open a new terminal session and check the default builder again using docker buildx ls. In this lab environment, the --default flag is sufficient to demonstrate the intended behavior of setting a persistent default for the current context.

Summary

In this lab, we learned how to manage Docker builder instances using the docker buildx command. We began by creating multiple builder instances, demonstrating how to add new builders beyond the default one. We then practiced listing these available builder instances using docker buildx ls to view their names, drivers, endpoints, and status. This step is crucial for understanding the available build environments.