ARTIFACTORY: Docker & OCI List Manifest Images Overrides

Overview

The introduction of specialized tools like Docker Buildx and Skopeo has revolutionized the creation and management of list manifest images. These tools have streamlined what was previously a complex process into a single-command operation. Their adoption has significantly reduced the time and effort required for manifest management while preserving a key feature: each image within a manifest list functions independently and can be pulled separately as a standalone image.

Understanding List Manifest Overrides

Overriding a list manifest image with another list manifest image is possible when the user has sufficient permissions to do so. In this process, only the list.manifest.json file is replaced, while the individual tags referenced previously in the original list.manifest.json continue to exist in the registry and remain accessible as standalone images. This behavior ensures that dependent systems can continue to pull specific tags directly, even after the list.manifest.json updates if they are pulled explicitly by their sha tag identifier. This characteristic is particularly important for maintaining system stability and enabling smooth transitions between different manifest versions.

Managing List Manifest Images Overrides

In some cases, customers still prefer the complete removal of all subsequent manifests that are referenced by the previous list.manifest.json. Our recommended approach for managing list.manifest image overrides in this case is to activate the Tag Retention Logic on the repository configuration. This ensures that each list.manifest including all it’s references are treated as a single unit, and any overwrite beyond the configured retention limit will result in the complete removal of the oldest list manifest revision and all its sub-manifest tags and content. 
It is important to note that applying this change to a repository with existing images will not retroactively remove them; it will only affect new content that is added moving forward.
Additionally, enabling Tag Retention will retain a minimum of one backup of the original list.manifest and all its subsequent tags. This ensures a safeguard for your previous state. In contrast, when Tag Retention is disabled, all subsequent tags are accumulated indefinitely unless managed through Cleanup Policies.

For more information on Tag Retention, see Use Tag Retention.

Alternative Approaches

If Retention Tags are not in use and you aim to remove image tags that are no longer referenced, the following three strategies are suggested for managing these tags efficiently.

Cleanup Policies

Available for Enterprise+ customers from Artifactory 7.98.7
Our main recommendation for managing obsolete tags is to implement Cleanup Policies in Artifactory. This automated approach offers several advantages:
 

• Automated cleanup based on predefined rules
• Consistent tag management across your organization
• Reduced risk of manual errors
• Configurable retention periods for compliance requirements

Specifically, the use of Cleanup Policies provides a native developer experience similar to dockerhub when using a policy 

For more information, see Cleanup Policies Guide & Docker Cleanup Method.

Delete Multi-Architecture Docker Tags

Starting from version 7.91.0, Artifactory supports the deletion of multi-architecture Docker tags along with all their sub-architectures using either the web UI or REST API. This operation must be performed prior to undertaking an override action. It is important to note that this operation involves pulling all existing manifests in the repository to avoid breaking potential duplicate links between a manifest and multiple list manifests.

Manual Tag Removal

A manual cleanup can be performed using API or via the webUI.
Note: Exercise caution when manually removing tags, as this operation cannot be undone. Always verify that the tags are no longer needed before deletion.

Support

If you need additional assistance or have questions about list manifest management, please contact our support team.