How to use docker manifest annotate command to add platform information

Introduction

In this lab, you will learn how to use the docker manifest annotate command to add platform information to a Docker manifest list. We will start by creating a manifest list that includes different architecture versions of the alpine image.

Following the creation of the manifest list, you will practice annotating individual manifests within the list to specify architecture, operating system, OS features, version, and architecture variants. Finally, you will inspect the annotated manifest list to verify the added platform information. This process is essential for building and distributing multi-architecture Docker images effectively.

Skills Graph

%%%%{init: {'theme':'neutral'}}%%%% flowchart RL docker(("Docker")) -.-> docker/ContainerOperationsGroup(["Container Operations"]) docker(("Docker")) -.-> docker/ImageOperationsGroup(["Image Operations"]) docker/ContainerOperationsGroup -.-> docker/inspect("Inspect Container") docker/ImageOperationsGroup -.-> docker/pull("Pull Image from Repository") docker/ImageOperationsGroup -.-> docker/tag("Tag an Image") subgraph Lab Skills docker/inspect -.-> lab-555168{{"How to use docker manifest annotate command to add platform information"}} docker/pull -.-> lab-555168{{"How to use docker manifest annotate command to add platform information"}} docker/tag -.-> lab-555168{{"How to use docker manifest annotate command to add platform information"}} end

Create a manifest list

In this step, we will learn how to create a manifest list. A manifest list is an index of image manifests, allowing you to reference multiple images for different architectures and operating systems with a single name. This is particularly useful for distributing multi-architecture images.

Before creating a manifest list, we need to have some images available. For this lab, we will use the alpine image for different architectures. We will pull the amd64 and arm64 versions of the alpine image.

First, pull the amd64 version of the alpine image:

docker pull alpine:latest

You should see output indicating the image is being pulled and extracted.

Next, pull the arm64 version of the alpine image. Note that we need to specify the platform for this pull.

docker pull --platform arm64 alpine:latest

Again, you will see output showing the image being pulled.

Now that we have the images, we can create a manifest list. We will use the docker manifest create command. This command takes the name of the manifest list you want to create, followed by the names of the images you want to include in the list.

Let's create a manifest list named my-alpine-list that includes the alpine:latest (amd64) and alpine:latest (arm64) images.

docker manifest create my-alpine-list alpine:latest alpine:latest --amend --amend

The --amend flag is used to add or update entries in the manifest list. We use it twice here because we are adding two images.

After running this command, you have created a manifest list. However, this list is only stored locally for now. In a later step, we will push it to a registry.

Annotate a manifest with architecture and OS

In this step, we will annotate the manifest list we created in the previous step. Annotating a manifest allows you to add metadata to it, such as the architecture and operating system the image is intended for. This information is crucial for Docker to select the correct image from a manifest list based on the environment where the container is being run.

We will use the docker manifest annotate command to add architecture and OS information to the entries in our my-alpine-list manifest list. The command takes the manifest list name, the image name within the list, and the annotation flags.

First, let's annotate the alpine:latest image that corresponds to the amd64 architecture and linux operating system.

docker manifest annotate my-alpine-list alpine:latest --arch amd64 --os linux

This command tells Docker that the alpine:latest image in the my-alpine-list manifest is for the amd64 architecture and the linux operating system.

Next, we will annotate the alpine:latest image that corresponds to the arm64 architecture and linux operating system.

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux

This command annotates the other alpine:latest image in the list, specifying it's for the arm64 architecture and linux operating system.

By annotating the manifest list with architecture and OS information, we make it possible for Docker to automatically select the correct image when a user pulls my-alpine-list on a system with a specific architecture.

Annotate a manifest with OS features and version

In this step, we will continue annotating our manifest list by adding information about OS features and version. While less common for basic images like Alpine, these annotations can be useful for images that require specific operating system capabilities or versions.

The docker manifest annotate command allows us to specify OS features using the --os-features flag and OS version using the --os-version flag.

Let's assume, for demonstration purposes, that our amd64 Alpine image requires a specific OS feature (e.g., fips) and is built for a specific OS version (e.g., 1.0). We will annotate the amd64 entry in our my-alpine-list with this information.

docker manifest annotate my-alpine-list alpine:latest --arch amd64 --os linux --os-features fips --os-version 1.0

This command updates the annotation for the amd64 entry in my-alpine-list, adding the specified OS feature and version.

Similarly, let's assume our arm64 Alpine image requires a different OS feature (e.g., selinux) and is built for a different OS version (e.g., 2.0). We will annotate the arm64 entry.

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux --os-features selinux --os-version 2.0

This command updates the annotation for the arm64 entry, adding its specific OS feature and version.

By adding these annotations, you provide more detailed information about the image's requirements and compatibility, which can be used by Docker or other tools when selecting an image from the manifest list.

Annotate a manifest with architecture variant

In this step, we will add architecture variant information to our manifest list. Architecture variants are used to distinguish between different versions or implementations of the same architecture. For example, the arm architecture has variants like v6, v7, and v8.

We use the docker manifest annotate command with the --variant flag to specify the architecture variant.

Let's assume our arm64 Alpine image is specifically built for the v8 variant of the arm64 architecture. We will annotate the arm64 entry in our my-alpine-list with this information.

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux --variant v8

This command updates the annotation for the arm64 entry in my-alpine-list, adding the v8 variant information.

For the amd64 architecture, variants are less common, but you could specify one if needed. For this lab, we will not add a variant to the amd64 entry.

By adding architecture variant information, you provide even more specific details about the image's compatibility, allowing Docker to select the most appropriate image for a given system.

Inspect the annotated manifest list

In this final step, we will inspect the manifest list we have created and annotated to see the information we have added. The docker manifest inspect command allows you to view the details of a manifest list, including the manifests it contains and their annotations.

To inspect our my-alpine-list manifest list, run the following command:

docker manifest inspect my-alpine-list

This command will output a JSON document representing the manifest list. You should see entries for both the amd64 and arm64 images, along with the annotations we added in the previous steps, such as architecture, os, os.features, and os.version, and variant.

Look for the manifests array in the output. Each object within this array represents an image included in the manifest list. You should be able to find the platform field within each manifest object, which contains the architecture, os, os.features, and os.version information. For the arm64 entry, you should also see the variant field.

Inspecting the manifest list is a good way to verify that your annotations have been applied correctly and that the manifest list is configured as you intended.

Summary

In this lab, we learned how to create a Docker manifest list, which serves as an index for multiple image manifests, enabling the distribution of multi-architecture images under a single name. We started by pulling alpine images for both amd64 and arm64 architectures. Subsequently, we used the docker manifest create command with the --amend flag to build a local manifest list named my-alpine-list, incorporating the pulled images.

Following the creation of the manifest list, we explored how to annotate individual manifests within the list using the docker manifest annotate command. This process involved adding crucial metadata such as architecture and operating system information. We specifically demonstrated how to annotate a manifest with architecture and OS details, and further explored adding OS features, version, and architecture variant information. Finally, we learned how to inspect the annotated manifest list to verify the added metadata, ensuring the list accurately reflects the characteristics of the included images.