ARTIFACTORY: How to Replace Multi-Arch Docker Manifests Using Strict Tag Overwrite

Description

This KB explains the behavior observed when both single-architecture and multi-architecture Docker images are pushed to the same Artifactory repository using the same tag. In this scenario, both manifest.json and list.manifest.json remain associated with the tag.

During a docker pull, the Docker client retrieves only the list.manifest.json, and the download count reflects only the manifest list.

The expected behavior is that when a new single-architecture image is pushed using a tag that was previously associated with a multi-architecture image, the existing multi-architecture manifest should be replaced so that only the latest single-architecture manifest remains associated with the tag and is returned during subsequent docker pull operations.

However, the current behavior is that the previously associated multi-architecture manifest continues to be returned during docker pull, even after the tag has been updated with a newer single-architecture image.



Reproduction steps

```
Create a simple Dockerfile:
```

FROM alpine:latest
# Bust cache so this layer reruns every build
ARG CACHEBUST=1
# Generate a random file at build time
RUN echo "Built at: $(date)" >> /foo.txt
CMD ["cat", "/foo.txt"]

```
Build the single-arch Docker image:
```

docker buildx build --push --sbom=false --provenance=false -t
myregistry.jfrog.io/docker-localtesting/testing:latest .

```
Build the multi-arch Docker image:
```

docker buildx build --push --sbom=true --provenance=mode=max -t
myregistry.jfrog.io/docker-localtesting/testing:latest .

When performing a Docker pull, the client only pulls the list.manifest.json, and in the download count, I can see entries for only list.manifest.json.

Solution

The multiple manifests per tag issue, the behavior you’re experiencing is caused by Artifactory’s default protection mechanism, which is designed to prevent accidental pushes of single-architecture images from overwriting or disrupting existing multi-architecture image manifests associated with the same tag.

To allow newer single-architecture pushes to fully overwrite and replace multi-architecture entries, you can enable the Enforce Strict Tag Overwrite feature introduced in Artifactory 7.144.2

To do this, navigate to Administration → Artifactory Settings → Packages Settings → Docker, OCI, HelmOCI and check Enforce Strict Tag Overwrite.

When this option is enabled, users must have Delete/Overwrite permissions to push an image using an existing name and tag. This ensures that multiple manifest types cannot coexist under the same tag.