How to use docker buildx imagetools inspect command to examine image details

Introduction

In this lab, you will learn how to use the docker buildx imagetools inspect command to examine the detailed information of Docker images. We will cover inspecting both single-platform and multi-platform images, demonstrating how to view their configuration, layers, and metadata.

You will also learn how to format the output of the inspection using Go templates for customized views and how to display the raw JSON manifest of an image for a complete understanding of its structure.

Skills Graph

Inspect a single-platform image

In this step, you will learn how to inspect a single-platform Docker image using the docker image inspect command. This command provides detailed information about an image, including its configuration, layers, and metadata.

First, let's pull a simple single-platform image. We will use the hello-world image for this example.

docker pull hello-world

You should see output indicating that the image is being pulled.

Using default tag: latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Now that we have the image, we can inspect it. Use the docker image inspect command followed by the image name.

docker image inspect hello-world

This command will output a large JSON object containing various details about the hello-world image. You will see information like the image ID, creation date, architecture, operating system, and configuration.

[
    {
        "Id": "sha256:...",
        "RepoTags": [
            "hello-world:latest"
        ],
        "RepoDigests": [
            "hello-world@sha256:..."
        ],
        "Parent": "",
        "Comment": "",
        "Created": "...",
        "Container": "...",
        "ContainerConfig": {
            ...
        },
        "DockerVersion": "...",
        "Author": "",
        "Config": {
            ...
        },
        "Architecture": "amd64",
        "Os": "linux",
        "Size": ...,
        "VirtualSize": ...,
        "GraphDriver": {
            ...
        },
        "RootFS": {
            ...
        },
        "Metadata": {
            ...
        }
    }
]

The output is a JSON array, even if you are inspecting a single image. This is because the command can accept multiple image names as arguments.

Inspect a multi-platform image

In this step, you will learn how to inspect a multi-platform Docker image. Multi-platform images are designed to run on different architectures and operating systems. When you pull a multi-platform image, Docker automatically selects the correct image for your system's architecture.

Let's pull a multi-platform image. We will use the alpine image, which is a lightweight Linux distribution.

docker pull alpine

You will see output similar to the previous step, indicating the image is being pulled.

Using default tag: latest
latest: Pulling from library/alpine
...
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

Now, let's inspect the alpine image using the docker image inspect command.

docker image inspect alpine

The output will again be a JSON object. Notice the Architecture and Os fields. These will reflect the architecture and operating system of the image that was pulled for your specific environment.

[
    {
        "Id": "sha256:...",
        "RepoTags": [
            "alpine:latest"
        ],
        "RepoDigests": [
            "alpine@sha256:..."
        ],
        "Parent": "",
        "Comment": "",
        "Created": "...",
        "Container": "...",
        "ContainerConfig": {
            ...
        },
        "DockerVersion": "...",
        "Author": "",
        "Config": {
            ...
        },
        "Architecture": "amd64",
        "Os": "linux",
        "Size": ...,
        "VirtualSize": ...,
        "GraphDriver": {
            ...
        },
        "RootFS": {
            ...
        },
        "Metadata": {
            ...
        }
    }
]

While the inspect command shows the details of the specific image pulled for your platform, it doesn't directly show the information about all the platforms the image supports in this default view. We will explore how to see more details about the image manifest in a later step.

Format the output using Go template

In this step, you will learn how to format the output of the docker image inspect command using Go templates. This allows you to extract specific pieces of information from the large JSON output and display them in a more readable format.

The docker image inspect command supports the --format flag, which takes a Go template string as an argument. Go templates allow you to access fields within the JSON output using dot notation.

Let's inspect the alpine image again, but this time we will format the output to show only the image ID and the architecture.

docker image inspect --format 'ID: {{.Id}}, Architecture: {{.Architecture}}' alpine

In this command, {{.Id}} accesses the Id field and {{.Architecture}} accesses the Architecture field from the JSON output.

You should see output similar to this, showing the ID and architecture of the pulled image:

ID: sha256:..., Architecture: amd64

You can access nested fields as well. For example, to get the operating system, which is within the main object, you would use {{.Os}}. Let's try displaying the ID, architecture, and operating system.

docker image inspect --format 'ID: {{.Id}}, Architecture: {{.Architecture}}, OS: {{.Os}}' alpine

The output will now include the operating system:

ID: sha256:..., Architecture: amd64, OS: linux

Go templates offer more advanced features like loops and conditional statements, but for simple extraction of fields, the dot notation is sufficient. This formatting is very useful when you need to script operations based on specific image properties.

Show the raw JSON manifest

In this step, you will learn how to view the raw JSON manifest of a Docker image. The manifest provides detailed information about the image, including the layers and the configurations for different architectures in the case of a multi-platform image.

To view the raw manifest, you can use the docker manifest inspect command. This command is particularly useful for understanding multi-platform images.

Let's inspect the manifest for the alpine image we pulled earlier.

docker manifest inspect alpine

This command will output a JSON object representing the image manifest. For a multi-platform image like alpine, this manifest will be a "manifest list" (also known as an "index"). This list contains entries for each supported architecture, pointing to the specific image manifest for that architecture.

You will see output similar to this (the exact content may vary slightly depending on the image version and your Docker setup):

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

Notice the manifests array. Each object in this array represents a specific image for a particular platform (architecture and OS). You can see the platform field indicating the architecture and operating system for each entry. The digest field is the unique identifier for the manifest of that specific platform image.

This raw manifest provides a deeper insight into how multi-platform images are structured and allows you to see all the different variants available under a single tag.

Summary

In this lab, you learned how to use the docker image inspect command to examine the details of Docker images. You started by inspecting a single-platform image, specifically the hello-world image, and saw how the command provides a comprehensive JSON output containing information like image ID, architecture, OS, and configuration.

You then moved on to inspecting a multi-platform image, understanding that the output for such images includes details about the different platforms supported. Finally, you explored how to format the output using Go templates to extract specific information and how to view the raw JSON manifest for a deeper look at the image's structure.