How to use docker manifest inspect command to view image manifests

Introduction

In this lab, you will learn how to use the docker manifest inspect command to view image manifests. We will begin by pulling a multi-architecture Docker image, specifically the alpine image, to understand how Docker handles images across different architectures.

Following the image pull, you will use docker manifest inspect to examine the manifest list associated with the multi-architecture image. You will then delve deeper by inspecting a specific image manifest within that list and finally explore the verbose output option of the docker manifest inspect command to gain a comprehensive understanding of image manifest details.

Skills Graph

Pull a multi-architecture image

In this step, we will learn how to pull a multi-architecture Docker image. A multi-architecture image is a single image tag that can be used across different architectures (like amd64, arm64, etc.). When you pull a multi-architecture image, Docker automatically selects the correct image layer for your system's architecture.

We will pull the alpine image, which is a lightweight Linux distribution commonly used in Docker containers. The alpine image is available as a multi-architecture image.

To pull the alpine image, open your terminal and run the following command:

docker pull alpine

This command tells Docker to download the latest version of the alpine image from Docker Hub. Since alpine is a multi-architecture image, Docker will download the image layers appropriate for the architecture of your LabEx VM.

You should see output similar to this, indicating that Docker is pulling the image:

Using default tag: latest
latest: Pulling from library/alpine
... (output showing download progress)
Digest: sha256:...
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

The Digest line shows the unique identifier for the specific image manifest that was pulled for your architecture.

After the command finishes, the alpine image will be available on your LabEx VM and ready to be used to run containers.

Inspect the manifest list of the multi-architecture image

In the previous step, we pulled the alpine image. Since alpine is a multi-architecture image, the tag alpine:latest actually refers to a manifest list. A manifest list is a list of image manifests, each for a different architecture. When you pull a multi-architecture image, Docker uses the manifest list to find the correct image manifest for your system.

To see the manifest list for the alpine:latest image, we can use the docker manifest inspect command. This command allows you to view the details of an image manifest or a manifest list.

Run the following command in your terminal:

docker manifest inspect alpine:latest

This command will output a JSON document representing the manifest list for the alpine:latest image. The output will show a list of manifests, each corresponding to a different architecture (like amd64, arm64, arm/v7, etc.). Each manifest in the list will have details like the platform (architecture and OS) and the digest (a unique identifier for that specific architecture's image manifest).

You will see output similar to this (the exact digests and number of manifests may vary):

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 528,
         "digest": "sha256:...",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 528,
         "digest": "sha256:...",
         "platform": {
            "architecture": "arm",
            "os": "linux",
            "variant": "v6"
         }
      },
      ...
   ]
}

This output confirms that alpine:latest is indeed a manifest list containing manifests for various architectures. This is how Docker knows which specific image to pull for your system when you use a multi-architecture tag.

Inspect a specific image manifest within the list

In the previous step, we inspected the manifest list for alpine:latest. This list contained multiple entries, each pointing to a specific image manifest for a different architecture. Now, let's inspect one of these specific image manifests.

To inspect a specific manifest, we need its digest. From the output of docker manifest inspect alpine:latest, find the digest for the architecture that matches your LabEx VM (which is amd64). The digest will look something like sha256:....

Once you have the digest for the amd64 manifest, you can inspect it using the docker manifest inspect command followed by the image name and the digest, separated by an @ symbol.

Replace YOUR_AMD64_DIGEST with the actual digest you found for the amd64 platform in the previous step's output.

docker manifest inspect alpine@YOUR_AMD64_DIGEST

For example, if the amd64 digest was sha256:f70734b6a266dcb51c52a820c34f3204cc6897445f6510b7a5be74d30a72f227, the command would be:

docker manifest inspect alpine@sha256:f70734b6a266dcb51c52a820c34f3204cc6897445f6510b7a5be74d30a72f227

This command will output a JSON document that represents the specific image manifest for the amd64 architecture. This manifest contains details about the image layers (identified by their digests) and the image configuration (also identified by a digest).

You will see output similar to this:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 1510,
    "digest": "sha256:..."
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 2803897,
      "digest": "sha256:..."
    }
  ]
}

This output shows the structure of a single image manifest, listing the configuration and the layers that make up the image for that specific architecture.

Inspect the manifest with verbose output

In the previous steps, we inspected the manifest list and a specific image manifest. The default output of docker manifest inspect provides a summary of the manifest or manifest list. To get more detailed information, including the full configuration of the image, we can use the --verbose flag.

Let's inspect the manifest list for alpine:latest again, but this time with the --verbose flag. This will show the manifest list and, for each manifest in the list, it will also show the full configuration details.

Run the following command in your terminal:

docker manifest inspect --verbose alpine:latest

This command will output a more extensive JSON document. For each entry in the manifests list, you will now see an additional field called Config. This Config field contains the full configuration of the image for that specific architecture, including details like the entrypoint, command, environment variables, working directory, and more.

You will see output similar to this (the exact details in the Config section will vary):

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 528,
         "digest": "sha256:...",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         },
         "Config": {
            "Env": [
               "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            ],
            "Entrypoint": [
               "/bin/sh"
            ],
            "Cmd": null,
            "WorkingDir": "/",
            ...
         }
      },
      ...
   ]
}

Using the --verbose flag is useful when you need to see the detailed configuration of the images within a manifest list, which can be helpful for debugging or understanding how a specific image is set up.

Summary

In this lab, we learned how to use the docker manifest inspect command to view image manifests. We started by pulling a multi-architecture image, alpine, understanding that a single tag can represent images for different architectures.

We then used docker manifest inspect to view the manifest list associated with the multi-architecture image, which details the available image manifests for various architectures. Finally, we explored how to inspect a specific image manifest within the list and how to obtain more detailed information using the verbose output option.