CODEWITHSUNDEEP
dockerhashdockerhubdocker-pull
Stanimir Mitko
Stanimir Mitko

Reputation: 443

Pulling docker image by digest

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

Upvotes: 44

Views: 64807

Answers (4)

Mohammad Ravanbakhsh
Mohammad Ravanbakhsh

Reputation: 3038

Solution:

You must pass image option to your command as follow :

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

For Example: (ubuntu 18.04)

docker image pull ubuntu:18.04@sha256:98706f0f213dbd440021993a82d2f70451a73698315370ae8615cc468ac06624

Upvotes: 46

BMitch
BMitch

Reputation: 263469

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.

Upvotes: 24

Shashank V
Shashank V

Reputation: 11183

The digest might be unique across all images in the docker repository but what do you think is the more common usage? Pulling an image named ubuntu or pulling an image named sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2?

Pulling using digest is also not common. Image tags are used.

eg: docker pull ubuntu:16.04

Upvotes: -5

Itamar Turner-Trauring
Itamar Turner-Trauring

Reputation: 3890

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.

Upvotes: 0

Related Questions