What is a container manifest?

docker dockerhub gcp docker-image
red888 picture red888 · Oct 30, 2017 · Viewed 13.6k times · Source

The only doc on this topic seems to assume I already know what a manifest is, the problem it solves, and how it fits into the docker ecosystem. After reading the doc I'm still not sure how manifests actually work.

My private GCR contains manifest files- don't really understand their purpose. Does docker hub also use manifest files? I can see they contain the layers and hashes of each layer, but I'm still unclear on how docker generates/uses them.

What is the purpose of a container manifest?

Answer

Phil E picture Phil E · Oct 30, 2017

The manifest types are effectively the JSON-represented description of a named/tagged image. This description (manifest) is meant for consumption by a container runtime, like the Docker engine.

Any registry or runtime that claims to have Docker distribution v2 API/v2.2 image specification support will be interacting with the various manifest types to find out:

  1. what actual filesystem content (layers) will be needed to build the root filesystem for the container, and..
  2. any specific image configuration that is necessary to know how to run a container using this image. For example, information like what command to run when starting the container (as probably represented in the Dockerfile that was used to build the image).

As a prior answer mentioned, a client (such as the docker pull implementation) talking to a registry will interact over the Docker v2 API to first fetch the manifest for a specific image/tag and then determine what to download in addition to be able to run a container based on this image. The v2 manifest format does not have signatures encoded into it, but external verification using tools like a notary server can be used to validate external signatures on the same "blob"/hash of content for full cryptographic trust. Docker calls this "Docker Content Trust" but does not require it when talking to a registry, nor is it part of the API flow when talking to an image registry.

One additional detail about manifests in the v2.2 spec: there is not only a standard manifest type, but also a manifest list type which allows registries to represent support for multiple platforms (CPU or operating system variations) under a single "image:tag" reference. The manifest list simply has a list of platform entries with a redirector to an existing manifest so that an engine can go retrieve the correct components for that specific platform/architecture combination. In DockerHub today, all official images are now actually manifest lists, allowing for many platforms to be supported using the same image name:tag combination. I have a tool which can query entries in a registry and show whether they are manifest lists and also dump the contents of a manifest--both manifest lists and "regular" manifests. You can read more at the manifest-tool GitHub repository.

Slide 12 from this talk on containerd design also has a nice graphical representation of how manifest lists link to manifests, which represent the image config and layers for a specific platform.

Related questions

In a Dockerfile, How to update PATH environment variable?

I have a dockerfile that download and builds GTK from source, but the following line is not updating my image's environment variable: RUN PATH="/opt/gtk/bin:$PATH" RUN export PATH I read that that I should be using ENV …

Read More
How to create User/Database in script for Docker Postgres

I have been trying to set up a container for a development postgres instance by creating a custom user & database. I am using the official postgres docker image. In the documentation it instructs you to insert a bash script …

Read More
How to pass arguments to a Dockerfile?

I am using RUN instruction within a Dockerfile to install a rpm RUN yum -y install samplerpm-2.3 However, I want to pass the value "2.3" as an argument. My RUN instruction should look something like: RUN yum -y install samplerpm-$arg …

Read More