DEV Community

Run [X]

Docker Images in Kubernetes : Image tags vs. Digest

Nilesh Sarupriya
・3 min read

Ever faced below problems with Images

I am unable to see my changes, even though I am using the referencing the image using the Correct Tag.
- Software Engineer developing something

I haven't changed the Referenced for the Image, but its behaviour changed.
- Software Engineer using something

What is Referencing?

Accessing a resource from a collection of similar resources is always easy when there is a versioning attached to it. It helps users to have a better control the specific resource that they are using.

This is useful when versioning attached to the resources is immutable. But at times, situations arise where one wants to have even more readability, for ex., using the latest version of the resource every time or raising a small patch so that it reflects in the version. In such cases, we would require the tags to be mutable.

Referencing in Docker Image in K8s

The usability around which the Docker Registry HTTP API V2 was built was to have Immutable references to the Images.

Having mutable tags gives the ability to have named versions, something which makes a lot of sense because things are kept easier on the pipelines, like take the latest image, use the dev image, or maybe when a fix is so small that it doesn’t require a version update.

So, now that the versions, a.k.a., tags, are mutable, does that mean there is nothing immutable that can be used to get the same Image again and again. This is where the Digest comes into the picture. This is a hash key that is created based on what all base images are used for constructing the image and this is unique for every different image. Same Digest can be used to reference the same image again and again.

Now let’s get into some techie stuff

Why are tags important?

Tags are human understandable reference to an Image used to convey information about that variant. An image can be tagged with multiple tags and can be referenced using any. Importantly, a tag can be changed to different images.

What is Non-deterministic Deployment?

When using Image tags for referencing the Image, there is no guarantee that the Tag would refer to the expected Image, because of Tag Mutability.

This drawback is for the Infrastructure Tools, which depend on State Changes, as the tools will not be able to find the difference in the state, if the Tag refers to a different image or not.

So, how do we make this deterministic?

In order to get the best of both the worlds, that is human understandable reference as well as deterministic deployments, there needs to be a Dynamic Mapping between Image Tag and Image Digest which can be used when deploying images. While pushing to a repository, we can tag the image and then once the digest is created, use that to deploy the images.

How can OPTA help?

What is Opta?

Opta is a platform for running containerized workloads in the cloud. It abstracts away the complexity of networking, IAM, K8s, and various other components - giving you a clean cloud agnostic interface to deploy and run your containers. It’s all configuration driven so you always get a repeatable copy of your infrastructure.

How does Opta help?

The "deploy" option of Opta with an image tag input would automatically create the Dynamic Mapping between the Image uploaded to the Repository and use the Image digest to deploy the Image. This guarantees that the new image is used every time regardless of the tag.

For more information on how to use Opta, please visit:

Discussion (0)