Pulling Images by Digest

The problem with tags

So far, we’ve shown you how to pull images using their name (tag). This is by far the most common method, but it has a problem: tags are mutable! This means it’s possible to accidentally tag an image with the wrong tag (name). Sometimes, it’s even possible to tag an image with the same tag as an existing but different image. This can cause problems!

Example

As an example, imagine you’ve got an image called golftrack:1.5, and it has a known bug. You pull the image, apply a fix, and push the updated image back to its repository using the same tag.

Take a moment to consider what happened there; you have an image called golftrack:1.5 that has a bug. That image is being used by containers in your production environment. You create a new version of the image that includes a fix. Then comes the mistake; you build and push the fixed image back to its repository with the same tag as the vulnerable image! This overwrites the original image and leaves you without a great way of knowing which of your production containers are using the vulnerable image and which are using the fixed image. They both have the same tag!

This is where image digests come to the rescue.

How image digests works

Docker 1.10 introduced a content-addressable storage model. As part of this model, all images get a cryptographic content hash. For the purposes of this discussion, we’ll refer to this hash as the digest. As the digest is a hash of the contents of the image, it’s impossible to change the contents of the image without creating a new unique digest. To put it another way, you cannot change the content of an image and keep the old digest. This means digests are immutable and provide a solution to the problem that we just talked about.

Every time you pull an image, the docker image pull command includes the image’s digest as part of the information returned. You can also view the digests of images in your Docker host’s local repository by adding the --digests flag to the docker image ls command. These are both shown in the following example.