Inspecting Image Metadata with Docker Inspect

You will extract configuration data and layer hashes from an image to verify its internal structure against the OCI specification.

In this lesson, you will learn how to use docker inspect to peer inside an image’s blueprint, revealing the hidden metadata and layer architecture defined by the OCI specification.

Peering Beneath the Surface

When you build an image, Docker packages your code along with environmental variables, command instructions, and a specific layer structure. Sometimes, you need to verify that your image was built as intended without running it. docker inspect acts as your X-ray machine, outputting the configuration of an image in a structured JSON format.

By running docker inspect <image_name>, you can retrieve deep details such as:

The Image ID: The unique cryptographic hash of the image.
Config: Details like the Entrypoint, Env variables, and the WorkingDir.
RootFS: The layer hashes that represent the file system changes made by each instruction in your Dockerfile.

Practical Verification

Imagine you want to verify the internal layers of an official alpine image. You can execute:

docker inspect alpine

This command returns a long JSON object. To focus on the layer structure specifically, you can use the --format flag to extract only the RootFS section:

docker inspect --format='{{json .RootFS.Layers}}' alpine

The output will be a list of SHA hashes. Each hash corresponds to a specific layer of your image. By comparing these hashes against your Dockerfile build logs (where you see each step being assigned a hash), you can verify that your image matches the exact OCI-compliant structure you built. If you change a single file or a RUN instruction, you will notice these hashes change, confirming the immutable nature of your image layers.

This tool is essential for CI/CD pipelines where you need to programmatically verify that an image configuration—like a critical security environment variable—is present before the image is pushed to a production registry.

Key Takeaway: docker inspect allows you to treat an image as a data structure, providing programmatic access to its internal configuration and immutable layer hashes to ensure your OCI-compliant build matches your expectations.