How to use docker buildx create command to manage builders

Introduction

In this lab, you will learn how to effectively manage Docker builders using the docker buildx create command. We will cover the essential steps of creating a new builder instance, appending new nodes to an existing builder, specifying custom names for builders and nodes, setting the supported platforms for a build node, and automatically switching to a newly created builder for your build operations. By the end of this lab, you will have a solid understanding of how to configure and utilize different builder setups for multi-architecture and distributed builds.

Skills Graph

Create a new builder instance

In this step, we will learn how to create a new builder instance using the docker buildx create command. A builder instance is a Docker object that manages multiple build nodes. Each node can represent a different architecture or environment for building images.

Before creating a new builder, let's check the existing builders on your system. You can do this using the docker buildx ls command.

docker buildx ls

You should see the default builder instance, which is usually named default.

Now, let's create a new builder instance. We will name this new builder mybuilder.

docker buildx create --name mybuilder

This command creates a new builder instance named mybuilder. By default, this new builder will not have any nodes associated with it yet. We will add nodes in the next steps.

After creating the new builder, you can list the builders again to see the newly created one.

docker buildx ls

You should now see both the default builder and the mybuilder builder listed. The mybuilder builder will be listed as inactive for now, as it doesn't have any active nodes.

Append a new node to an existing builder

In the previous step, we created a new builder instance named mybuilder. Currently, this builder doesn't have any build nodes. In this step, we will append a new node to this existing builder.

A build node is essentially a Docker endpoint where the build process will run. By default, when you create a new builder without specifying a node, it's created without any active nodes.

To append a new node to the mybuilder builder, we will use the docker buildx create command again, but this time we will specify the builder to which we want to append the node using the --append flag. We will append a node to the mybuilder builder.

docker buildx create --name mybuilder --append

This command appends a new node to the mybuilder builder. By default, when you append a node without specifying a name, Docker Buildx will generate a name for it.

Let's list the builders again to see the updated mybuilder instance with the new node.

docker buildx ls

You should now see mybuilder listed with a node underneath it. The node will have a generated name and will likely be in a running state.

Specify a name for the builder and node

In the previous steps, we created a builder named mybuilder and appended a node to it. The node was automatically assigned a generated name. In this step, we will learn how to specify names for both the builder and the node when creating them.

First, let's remove the mybuilder builder we created in the previous steps so we can start fresh.

docker buildx rm mybuilder

Now, let's create a new builder instance and specify its name as custombuilder. We will also specify a name for the initial node within this builder as node1. We can do this by using the --name flag for the builder and the --node flag for the node.

docker buildx create --name custombuilder --node node1

This command creates a new builder instance named custombuilder and an initial node within it named node1.

Let's list the builders to confirm the names.

docker buildx ls

You should now see custombuilder listed, and underneath it, you should see the node named node1. This gives you more control over how your builders and nodes are organized and identified.

Set the platforms supported by a node

In this step, we will learn how to specify the platforms that a build node supports. This is crucial for building multi-architecture images. By default, a node will support the architecture of the host it is running on. However, with Buildx, you can configure nodes to support additional platforms using emulation (like QEMU).

First, let's inspect the custombuilder we created in the previous step to see the platforms supported by its node.

docker buildx inspect custombuilder

Look for the "Platforms" field in the output. It should show the native architecture of your LabEx VM (e.g., linux/amd64).

Now, let's update the node1 within custombuilder to support additional platforms. We can use the docker buildx create command with the --append flag and the --platform flag. We will add support for linux/arm64 and linux/riscv64.

docker buildx create --name custombuilder --append --node node1 --platform linux/arm64,linux/riscv64

Note that we are using --append with the existing builder name and node name. This command updates the existing node node1 within custombuilder to include the specified platforms.

Let's inspect the builder again to see the updated platforms for node1.

docker buildx inspect custombuilder

The "Platforms" field for node1 should now include linux/amd64, linux/arm64, and linux/riscv64. This means this node is now capable of building images for these architectures.

Automatically switch to the newly created builder

In this final step, we will learn how to automatically switch to using the newly created builder instance. When you have multiple builders, you need to tell Docker Buildx which one to use for your build operations.

By default, Docker Buildx uses the default builder. You can see which builder is currently active by looking at the output of docker buildx ls. The active builder will have an asterisk (*) next to its name.

docker buildx ls

To switch to using the custombuilder we created, you can use the docker buildx use command followed by the name of the builder.

docker buildx use custombuilder

This command sets custombuilder as the currently active builder. Any subsequent docker buildx build commands will now use the nodes configured within custombuilder.

Let's verify that custombuilder is now the active builder by listing the builders again.

docker buildx ls

You should now see an asterisk (*) next to custombuilder, indicating that it is the active builder.

You have successfully created a new builder instance, added a node to it, specified names for both, set the supported platforms for the node, and switched to using this new builder.

Summary

In this lab, we learned how to manage Docker builders using the docker buildx create command. We started by creating a new builder instance named mybuilder, demonstrating how to initialize a separate build environment. We then explored how to append a new build node to an existing builder, effectively adding a build endpoint to our mybuilder instance.

Furthermore, we covered how to specify custom names for both the builder and its nodes for better organization and clarity. We also learned how to define the specific platforms (architectures) that a particular build node supports, enabling targeted builds. Finally, we practiced automatically switching to the newly created builder, making it the active builder for subsequent build operations.