How to use docker buildx ls command to list builder instances

Introduction

In this lab, you will learn how to use the docker buildx ls command to list builder instances and their associated nodes. You will explore the basic usage of the command to view available build environments and their configurations.

Furthermore, you will discover how to format the output of docker buildx ls using Go templates to customize the displayed information. This includes formatting the output to show specific fields and to visualize the relationships between builder instances and their nodes.

Skills Graph

List all builder instances and nodes

In this step, you will learn how to list all builder instances and nodes using the docker buildx ls command. This command is useful for understanding the available build environments and their configurations.

First, let's execute the basic command to list the builder instances and nodes.

docker buildx ls

You should see output similar to this:

NAME/NODE       DRIVER/ENDPOINT STATUS  BUILDKIT             PLATFORMS
default         docker
  default       docker          running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x

The output provides information about the builder instances and their associated nodes. The NAME/NODE column shows the name of the builder instance and the node within that instance. The DRIVER/ENDPOINT column indicates the driver used and the endpoint for the node. The STATUS column shows the current status of the node (e.g., running). The BUILDKIT column displays the BuildKit version. Finally, the PLATFORMS column lists the supported platforms for the node.

In this example, we see a builder instance named default with a single node also named default. It is using the docker driver and is currently running. It supports multiple platforms.

Format the output using a Go template

In this step, you will learn how to format the output of the docker buildx ls command using a Go template. Go templates provide a flexible way to customize the output format to display only the information you need.

The --format flag allows you to specify a Go template. The template uses placeholders like {{.Name}}, {{.Driver}}, {{.Status}}, etc., to access the different fields of the builder instance and node objects.

Let's try formatting the output to show only the name and driver of the builder instances and nodes.

docker buildx ls --format "{{.Name}}\t{{.Driver}}"

You should see output similar to this:

default docker
default docker

In this template, {{.Name}} represents the name of the builder or node, and {{.Driver}} represents the driver. The \t is used to insert a tab character between the name and the driver for better readability.

This demonstrates how you can use a simple Go template to extract specific information from the docker buildx ls output. In the following steps, we will explore more complex templates to format the output in different ways.

Format the output with specific fields

In this step, we will continue exploring Go templates to format the output of docker buildx ls and display specific fields of interest. You can select various fields from the builder instance and node objects to include in your custom output.

Let's format the output to show the name, status, and supported platforms for each builder node.

docker buildx ls --format "{{.Name}}\t{{.Status}}\t{{.Platforms}}"

You should see output similar to this:

default running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x
default running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x

In this template:

• {{.Name}} refers to the name of the builder node.
• {{.Status}} refers to the status of the builder node (e.g., running).
• {{.Platforms}} refers to the list of supported platforms for the builder node.

We are using \t again to separate the fields with tabs. This allows you to quickly see the status and supported platforms for each node.

You can combine different fields in your template based on your needs. Experiment with including other fields like {{.Driver}} or {{.Buildkit}} to see how the output changes.

Format the output to show builder and node relationships

In this step, we will use a more advanced Go template to visualize the relationship between builder instances and their nodes. This can be helpful when you have multiple builder instances and nodes configured.

We can use conditional statements and loops within the Go template to achieve this. However, for simplicity and to focus on the basic formatting, we will create a template that clearly shows which node belongs to which builder instance.

Let's use a template that prints the builder name followed by its nodes, indented.

docker buildx ls --format "{{range .}}{{if .Builder}}{{.Name}} (Builder){{range .Nodes}}\n  - {{.Name}} (Node){{end}}{{else}}\n{{.Name}} (Node){{end}}{{end}}"

You should see output similar to this:

default (Builder)
  - default (Node)

Let's break down this template:

• {{range .}}...{{end}}: This iterates over the list of builder instances and nodes.
• {{if .Builder}}...{{else}}...{{end}}: This checks if the current item is a builder instance (.Builder is true).
• If it's a builder:
  • {{.Name}} (Builder): Prints the builder's name followed by "(Builder)".
  • {{range .Nodes}}...{{end}}: This iterates over the nodes within the current builder.
  • \n - {{.Name}} (Node): Prints a newline, an indentation, "- ", the node's name, and "(Node)".
• If it's not a builder (meaning it's a standalone node, though less common in basic setups):
  • \n{{.Name}} (Node): Prints a newline, the node's name, and "(Node)".

This template provides a structured output that clearly shows which nodes are associated with which builder instances. While this example is simple with only one builder and one node, this template becomes more useful when you have a more complex buildx configuration.

Summary

In this lab, you learned how to use the docker buildx ls command to list builder instances and their associated nodes. You started by executing the basic command to see the default output, which provides details about the builder name, node name, driver, status, BuildKit version, and supported platforms.

Furthermore, you explored how to format the output using a Go template with the --format flag. This allows you to customize the displayed information by specifying placeholders for different fields, enabling you to extract and present only the relevant data about your builder instances and nodes.