Docker Hub Immutable Tags
Immutable tags give you a guarantee that an image hasn't changed over time which can be useful for reproducibility.
Immutable means it cannot change where as mutable means it can change.
As an image publisher, immutable tags protect yourself from overwriting an existing tag with different content.
As an image consumer, immutable tags give you confidence that an image hasn’t changed on you over time. Technically you can get similar behavior by locking your image tags down to a specific digest, I’ve written about that in the past.
# Pros and Cons
With that said, depending on how you want to publish your images, there are pros and cons for using immutable images.
One pro of mutable tags is it can make getting security updates easier since if
you reference something like debian:trixie-slim today or 3 months from now
you will get a different image based on new security patches being applied over
time. The benefit there is you don’t have to make a Dockerfile change, you
can just rebuild.
Funny enough depending on what you’re optimizing for, you can also see that as a con because if you build an image today or 3 months from now but get a different result then technically you don’t have a reproducible build.
From an auditing perspective knowing exactly when a new image got built and rolled out is helpful, that’s where having explicit tags or SHAs changing is a good thing.
Security patches aren’t the only way an image can change, that was only 1 example.
No matter which option you choose, having support for immutable tags is a good feature to have available. It allows image publishers to create a contract with you which states an image tag won’t change over time.
# Immutable Tags
As for how it’s implemented on the Docker Hub, it’s done at the repo level which means you can choose where to apply them. Tags are mutable by default which means this new feature isn’t going to modify existing set ups.
On a per repo basis, you can choose between these in the repo’s settings:
- All tags are mutable
- All tags are immutable
- Specific tags are immutable
Changing any of the settings and saving it takes effect within seconds.
The last one is interesting because it lets you set up regex based rules to
only make specific tags immutable. For example maybe you want latest to be
mutable but everything else immutable, or maybe only specific release tags are
immutable, etc..
The video below goes over configuring a repo and demonstrating the above in more detail.
# Demo Video
Timestamps
- 0:24 – Pros and cons of immutable vs mutable
- 2:20 – Preparing a repo
- 3:52 – Tag settings
- 4:10 – All tags are immutable
- 5:50 – Specific tags are immutable (regex)
- 8:12 – Always save your settings
- 9:21 – Reminder, it’s a per repo setting
Will you start using this feature? Let us know below.