#docker pull <image_name>:<tag>
docker pull ubuntu:22.04

#docker pull <image_name>@<digest>
docker pull ubuntu@sha256:bace9fb0d5923a675c894d5c815da75ffe35e24970166a48a4460a48ae6e0d19

Deterministic deployment is not guaranteed if we use the first approach above that uses the tag. The exact same image isn't guaranteed to be pulled if we use the tag, the image might have been patched for a CVE and therefore the tag remains the same but the digest changes. Read more here.

Introduction

When working with Docker containers, one crucial aspect is pulling and managing Docker images. Docker images serve as the building blocks for containers and contain everything required to run an application. In this post, we'll explore the differences between pulling images by tags and digest and understand when each approach is appropriate.

1. Pulling by Tags:

Docker images are typically tagged with versions or labels to differentiate between different releases or variations of an application. Pulling an image by its tag is the most common and straightforward method.

Benefits of pulling by tags:

  • Ease of use: Pulling an image by its tag is simple, using the docker pull command followed by the image name and tag.
  • Semantic versioning: Tags often follow a versioning scheme, allowing users to specify a particular release or version of an image.
  • Flexibility: Tags can represent different variants of an image, such as different operating systems, architectures, or configurations.

However, there are a few considerations when using tags:

  • Mutable references: Tags can be mutable, meaning that the same tag can point to different images over time. This can result in unexpected changes when pulling an image with a previously used tag.
  • Potential for breaking changes: Using a tag like "latest" may seem convenient, but it can lead to compatibility issues if the latest image introduces breaking changes or bugs.

2. Pulling by Digest:

A digest is a unique identifier generated from the image's content, providing an immutable reference to an image. It is calculated using a cryptographic hash function (SHA256) and remains unchanged unless the image itself is modified.

Advantages of pulling by digest:

  • Guaranteed immutability: When pulling an image by its digest, you ensure that you retrieve the exact image with the specific content you expect, regardless of any changes made to the tag.
  • Enhanced security: Digests act as fingerprints for images, making it easier to verify their integrity and ensuring that you're using the intended image without any tampering.

Considerations when using digests:

  • Complexity: Digests are long and complex strings of characters that are not human-friendly. This can make them less convenient to work with compared to tags.
  • Limited discoverability: While tags provide a meaningful way to identify images, digests don't carry any semantic information, making them harder to search or remember.

Conclusion:

Choosing between pulling Docker images by tags or digest depends on your specific requirements and preferences. Tags offer flexibility and ease of use, making them suitable for most scenarios. However, if you prioritize immutability, and security, and want to ensure the exact content of an image, using digests provides a reliable option.

Remember to consider the trade-offs between convenience and immutability when deciding which approach to use. Whether you opt for tags or digests, understanding these concepts will empower you to efficiently manage your Docker images and create consistent and reliable container deployments.