Docker Manifest – A Peek Into Image’s Manifest.json Files

Docker Manifest – An Experimental Feature!

The image manifest provides a configuration and a set of layers for a container image.

This is an experimental feature. To enable this feature in the Docker CLI, one can edit the config.json file found in ~/.docker/config.json like :

xxxxxxxxxx

{

        "auths": {

                "https://index.docker.io/v1/": {

                        "auth": "XXXXXXX"

                }

        },

        "HttpHeaders": {

                "User-Agent": "Docker-Client/19.03.8 (linux)"

        },

        "experimental": "enabled",

        "debug": true

}

What Is ‘Docker Manifest’?

The docker manifest command does not work independently to perform any action. In order to work with the docker manifest or manifest list, we use sub-commands along with it. This manifest sub-command can enable us to interact with the image manifests. Furthermore, it also gives information about the OS and the architecture, that a particular image was built for.

A single manifest comprises of information about an image, it’s size, the layers and digest.

A manifest list is a list of image layers (manifests) that are, created by specifying one or more image names. It can then be used in the same way as an image name in docker pull and docker run commands.

Commands to Get Started With:

After enabling this feature, one would be able to access the following command :

These commands are easy to use. It basically avoids the need for pulling and running and then testing the images locally, from a docker registry.

Next, to inspect an image manifest, follow this syntax,

docker manifest inspect image-name

As we can see, the image hello-world supports many different architectures.

As a result, it becomes very easy to identify the list of platforms that an image can run upon, without the need for ” pulling ” that image on that platform and then running it, to test if it supports such architecture or not.

Image Layers

In this section, we will be talking about the image layers, their architecture.Each of the files that make up a docker image is known as a layer.These layers form a series of intermediate images, built one on top of the other in stages, where each layer is dependent on the layer immediately below it.

The hierarchy in which the layers are organized is very important, the layers that change frequently should be placed as high up the hierarchy as possible. This helps in efficient management of a docker image’s life cycle.

This is because, when one makes changes to a layer in your image, docker not only rebuilds that particular layer but all layers built from it. Therefore a change to a layer at the top of the stack involves the least amount of computational work to rebuild the entire image. Thus the layers with the least or can be said with no changes are kept at the bottom of the hierarchy formed.

Let’s Walk Through an Example

We start with building a dockerfile with the following contents,

FROM ubuntu:18.04
RUN echo "Hi Visitor."

When we build this dockerfile with no-cache option,

This results in creation of an image digest.

Upon exploring this image digest, we get

Components of an Image Digest

Let’s discuss each of these components:

Config file –
Docker’s JSON config file describes the environment that built the docker image and its history.
( here, 5d1cdcfd1c744987e4916f7815874391b29bff62e3df2d29885683e1b39e4c0a.json )

manifest.json file –
The manifest.json file describes the location of the layers and config file.

Layers

Each layer is comprised of a json file (which looks like the config file), a VERSION file with the string 1.0 , and a layer.tar file containing the images files.

Looking into the manifest.json file,

The layers section here depicts all the layers as a directory having its own filesystem and layers built on top of the other forms an image. Each layer has it’s own version file, a json file, and a layer filesystem.

An important Note : This layer.tar SHA is referenced inside the config file, and the location of the layer is in the manifest.

NOTE:
When the same dockerfile is built again, a new digest is created for that build, irrespective of the fact, that the same file is being built again and in the same environment. The only difference that makes these two different digests is the container.key and the creation-timestamp.

Coming back to the manifest command,
We can use manifest command with a set of sub-commands, like,

• Manifest create: To create a manifest / manifest list locally in order to annotate and push to a registry.
• Manifest annotate: To provide additional information to a local image manifest / manifest list.

Annotations allowed are the architecture and the operating system (overriding the image’s current values), OS features, and architecture variant values.

• Manifest push: To push a manifest / manifest list to a repository.

I hope this blog gives you a brief understanding of the concept of manifest files. One can always refer to the official documentation of Docker, for more information.