Pulling Images by Digest

The problem with tags

So far, we’ve seen how to pull and work with images using names (tags). While this is the most common method, it has a problem — tags are mutable. This means it’s possible to tag an image incorrectly or give a new image the same tag as an older one. An extremely common example is the latest tag. For example, pulling the alpine:latest tag a year ago will not pull the same image as pulling the same tag today.

Example

Consider a quick example outlining one potential implication of trusting mutable tags. Imagine we have an image called golftrack:1.5 and we get a warning that it has a critical vulnerability. We build a new image containing the fix and push the new image to the same repository with the same tag. Take a moment to consider what just happened and the implications.

We have an image called golftrack:1.5 that’s being used by lots of containers in our production environment, and it has a critical bug. We create a new version containing the fix. So far, so good, but then we make the mistake. We push the new image to the same repository with the same tag as the vulnerable image. This overwrites the original image and leaves us without a great way of knowing which of our production containers are using the vulnerable image and which are using the fixed image — both images have the same tag! This is where image digests come to the rescue.

How image digests work

Docker uses a content addressable storage model where every image gets a cryptographic content hash that we usually call the digest. As these are hashes of an image’s contents, it’s impossible for two different images to have the same digest. It’s also impossible to change an image without creating a new unique digest. Fortunately, Docker allows us to work with image digests in addition to names.

If we’ve already pulled an image by name, we can see its digest by running a docker images command with the --digests flag as shown.