Pulling docker image by digest

Question

I would like to ask why it is needed to specify both name and digest when pulling docker image?

docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

Isn't it enough, just to pass the digest, or the digest is not unique enough in the context of the whole docker repository?

For example like that:

docker pull sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

Solution 1

Images are pulled from registries. Image names include the registry, e.g. quay.io/yourgroup/yourimage pulls from quay.io server.

But ubuntu doesn't include the server name, you say?

If there's no server name, it defaults to the Docker Hub, aka docker.io. So ubuntu is the same as docker.io/library/ubuntu.

Thus, you need to have the name so it knows which image registry server to talk to.

Solution 2

You must pass image option to your command as follow :

docker image pull [OPTIONS] NAME:[TAG@DIGEST]

For Example:

docker image pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

Solution 3

The name is required because of how the registry API is designed. Image pulls in docker all go back to a repository on a registry server. A repository is a path on the server, containing multiple image manifests, along with other blobs (image configs, layers, and possibly other data pulled by a digest).

One key reason to run all API requests against a repository, rather than the overall registry, is to handle authorization. Otherwise, each request for a digest would need to do a reverse lookup of all repositories that reference that digest, and see if the user has permission to access that digest.

You also wouldn't run a request against some global registry namespace since there's more than one registry, and new registries can be easily created. Docker Hub may be the most popular, but there are also registries for most cloud providers, CI providers like GitHub and GitLab, and self hosted registries on company networks, in their own production clusters, and on developer laptops. Therefore there's no upper limit to how long that request could take, and a discovery method would be needed to find new registries, including those that may have been created in your private network.

---

For a deeper dive, the api for a pull will request:

GET /v2/<name>/manifests/<reference>

The name and reference parameter identify the image and are required. The reference may include a tag or digest.

(The "name" referenced in that documentation is the repository name.)

The docker commands mirror this API design, requiring the image name. If you leave off the tag or digest, it will use "latest" as a default value. When you leave off the registry name, it defaults to Docker Hub. And if you also left off a username, it prefixes the registry name with library/ where all the official images are located on Docker Hub.

So the pull request for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 will turn into a request to registry-1.docker.io (the registry API server for Docker Hub) for the repository library/ubuntu with the reference of the sha256 you listed.

Attempting to leave off the repository name from the pull will result in an invalid syntax (docker will call this a reference format) because it cannot extrapolate the repository from nothing and there is no default repository name.

Comments

[Stanimir Mitko]

Thanks for the answer!! Indeed tags are more common, but I think using digest depends on the use case. When we want to ensure that the integrity of the image is not violated, I think more appropriate is to use digest. However, I went off-topic since the use case is not part of the question.

[Stanimir Mitko]

Thanks for the answer Itamar! I think I understood your point here. I forgot that name actually includes the registry which we pull from. In this case, using only digest would not point in which docker registry the image should be located. I think this should be the accepted answer!

[Jonathan Adami]

I'd argue that it should be more common though, in my team we had issues with inconsistent images across different employee. We used FROM image:tag but depending on when you build your local image you might have a different result. We now pull with image:tag@digest just to make sure we all use the same base. It helps with tracking security updates and all that.

[Shashank V]

That is the problem with your practices. Once an image is pushed to a repository with an image:tag name, it should not be allowed to be overwritten. Only latest tag is exception for this rule and latest should not be used as base image by others.

[BMitch]

The OP was asking "Isn't it enough, just to pass the digest, or the digest is not unique enough in the context of the whole docker repository?"