ARTIFACTORY: Docker Max Unique Tags and Retention Policies - Practical Guide
In this guide, we will delve into configuring Docker tags and retention policies for local repositories. Whether setting the maximum tags greater than retention or vice versa, this guide will provide practical examples to demonstrate the implications of each configuration. By default, Max Unique Tags is set to zero (0) and Tag Retention is set to one (1). In order to activate it, we will implement higher values so that it will then apply FIFO (first in, first out) logic.
Example 1When configuring the Docker Local Repository as follows:
Max Unique Tags: 2
Docker Tag Retention: 3
In this example, we divided the process into two distinct tags and uploaded four images under each tag, demonstrating the "overwriting" aspect relative to "Retention". It's important to note that tags are preserved only up to the maximum allowed we set in our repository configuration.
First we downloaded four Nginx images from an upstream source, each with a unique IMAGE ID and Size. Then we began to tag these images and push them to our docker-test-local repository using the same format for each, such as:
<DOCKER_IMAGE>:<DOCKER_TAG>; ex:( nginx:1.0 ).
Upon pushing our first docker image, the retention-based overwriting has not yet occurred. The SHA value for this initial image is stored under manifest.json with the tag 1.0. However, as subsequent images are pushed, overwriting begins to occur, and the effects of retention policies take place:
After completing the initial phase of uploading three images, we proceeded to push a fourth image. Since this exceeded the Tag Retention limit of 3, the oldest 'Latest' tag iteration (SHA 1)—which corresponds to the original first push—was removed.
Upon pushing the latest image, the corresponding sha256 value can now be found in the manifest.json file:
As we can see the Retention will stay less than or equal to 3
Docker Tag Retention - By default, pushing a docker image to an Artifactory with an identical name:tag as an existing image in that Docker repository will result in the older image being overwritten. By increasing the Docker Tag Retention value, you can preserve multiple versions of the same image:tag within the same repository. In this setup, the most recently pushed image retains the original tag, while older images are tagged with their digest SHA value. This allows for better version management and traceability within your Docker repository.
Example 2When configuring the Docker Local Repository as follows:
Max Unique Tags: 3
Docker Tag Retention: 2
For this example, we will assign two different tags to images and then push three images for each tag to initiate the Retention process.
In this setup, each tag is associated with its own Sha256 retention values, allowing a maximum of two Sha256 retention values per tag. With two tags in use, this results in a total of four Sha256 values. However, upon pushing an additional image (whether under tag 2.0 or 2.1), one of the existing Sha256 values will be removed. This reduction leaves us with three remaining Sha256 retention values. The Sha256 of the newly pushed image is then recorded in the manifest.json file corresponding to that specific tag, maintaining the updated retention count.
Overall, the main implication of applying both Max Unique Tags and Tag Retention together is that Max unique tags take precedence and will remove all retention revisions associated with the current tag if it is being deleted by the logic. This means that if a tag is removed due to exceeding the Max Unique Tags limit (being the oldest unique tag when a new one has been pushed), all of its Tag Retention copies will be removed as well.
Please Note: There are limitations as well with the Tag Retention Logic - reference:
https://jfrog.com/help/r/jfrog-artifactory-documentation/limitations-of-tag-retention-logic
Reference: For more in depth information regarding the Tag Retention Logic please refer to our documentation:
https://jfrog.com/help/r/jfrog-artifactory-documentation/tag-retention-logic