How to use docker buildx history rm command to remove build records

Introduction

In this lab, you will learn how to manage build records using the docker buildx history rm command. Build records are valuable for tracking your build processes and their outcomes.

You will begin by creating a build record using docker buildx build and saving its metadata. Then, you will learn how to list existing build records using docker buildx ls to view their details. Finally, you will practice removing specific build records and clearing all build records using the docker buildx history rm command.

Skills Graph

Create a build record

In this step, you will learn how to create a build record using the docker buildx build command. Build records are useful for tracking the results of your builds, including the build context, build arguments, and the resulting image ID.

First, let's create a simple Dockerfile that we will use for building. Navigate to your project directory and create a file named Dockerfile with the following content:

FROM alpine
CMD ["echo", "Hello, Docker!"]

This Dockerfile is very simple. It uses the alpine base image and defines a command to print "Hello, Docker!".

Now, let's build an image from this Dockerfile and create a build record. We will use the docker buildx build command with the --metadata-file flag to save the build record to a file.

docker buildx build . --metadata-file build-record.json -t my-hello-image

In this command:

• docker buildx build . tells Docker to build an image from the Dockerfile in the current directory.
• --metadata-file build-record.json specifies that the build record should be saved to a file named build-record.json.
• -t my-hello-image tags the resulting image with the name my-hello-image.

After running the command, you should see output indicating the build process. A file named build-record.json will be created in your current directory. This file contains the build record in JSON format.

You can view the content of the build-record.json file using the cat command:

cat build-record.json

This will display the JSON content of the build record, which includes information about the build.

List build records

In this step, you will learn how to list existing build records using the docker buildx ls command. This command allows you to see a list of all build records that have been created.

To list the build records, simply run the following command:

docker buildx ls

This command will display a table with information about the available build records. The output typically includes the builder name, the driver used, and the status.

You should see an entry for the default builder, which is used when you run docker buildx build. The build record we created in the previous step is associated with this builder.

The docker buildx ls command is useful for getting an overview of your build environments and the associated build records.

Remove a specific build record

In this step, you will learn how to remove a specific build record using the docker buildx prune command. This is useful for cleaning up individual build records that you no longer need.

To remove a specific build record, you need to identify its ID. You can find the build record ID in the build-record.json file we created in the first step. Open the file using cat:

cat build-record.json

Look for the "BuildRecord" section in the JSON output. Inside this section, you will find an "ID" field. Copy the value of this ID. It will be a long string of characters.

Now, use the docker buildx prune command with the --keep-storage flag and the build record ID to remove the specific record. Replace <BUILD_RECORD_ID> with the actual ID you copied.

docker buildx prune --keep-storage <BUILD_RECORD_ID>

The --keep-storage flag is used here to indicate that we are pruning build records, not build cache.

After running the command, you should see output confirming that the build record has been removed.

To verify that the build record is removed, you can try to list the build records again:

docker buildx ls

The specific build record you removed should no longer appear in the list.

Remove all build records

In this step, you will learn how to remove all build records using the docker buildx prune command with the --all flag. This is a convenient way to clean up all build records at once.

To remove all build records, run the following command:

docker buildx prune --all --keep-storage --force

In this command:

• docker buildx prune is the command for removing build-related data.
• --all specifies that all build records should be removed.
• --keep-storage indicates that we are pruning build records, not build cache.
• --force bypasses the confirmation prompt, which is useful for scripting or in environments where interaction is not possible.

After running the command, you should see output indicating that the build records have been removed.

To verify that all build records are removed, you can list the build records again:

docker buildx ls

You should now see only the default builder entry, and no specific build records listed under it.

This concludes the lab on managing Docker build records. You have learned how to create, list, and remove build records.

Summary

In this lab, you learned how to manage Docker build records using docker buildx. You started by creating a simple Dockerfile and then used docker buildx build with the --metadata-file flag to build an image and generate a build record, saving it to a JSON file. You then learned how to list existing build records using the docker buildx ls command to view information about your builds.

The lab also covered how to remove specific build records using docker buildx history rm <record_id> and how to remove all build records at once using docker buildx history rm --all. These steps demonstrate the lifecycle management of build records within Docker Buildx.