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

Answer 1

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.