The Guide to ACR Manifests - Automated and Manual Manifest Deletion Strategies

About Manifests

An image manifest is a JSON document that describes everything needed to pull and run a container image. Typically includes:

• References to image layers (the digests of all filesystem layers that make up the image).
• Configuration metadata (environment variables, entrypoint command, exposed ports, labels, architecture, and OS).
• Content digest (cryptographic hashes that ensure layers and config have not changed).
• Compatibility info — which platforms (e.g., linux/amd64, windows/amd64) the image supports.

Each container image or artifact pushed to a container registry is associated with a manifest. The manifest, generated by the registry when the content is pushed, uniquely identifies the artifacts and specifies the layers.

Manifests are identified by a unique SHA-256 hash, or manifest digest. Each image or artifact–whether tagged or not–is identified by its digest. The digest value is unique even if the artifact’s layer data is identical to that of another artifact. This mechanism is what allows you to repeatedly push identically tagged images to a registry. For example, you can repeatedly push myimage:latest to your registry without error because each image is identified by its unique digest.

Tagged and Untagged Manifests

When you push a new image with the same tag, the previous version loses its tag and becomes an “untagged” manifest. These untagged images still occupy space in the registry but are not visible under a tag. This often happens with automated build systems that push new versions using the same tags. Additionally, layer reuse and caching can contribute to untagged manifests. If your build process reuses layers across different tags without applying a new one, or if the pipeline doesn’t tag images correctly, untagged manifests can accumulate.

Automatic cleaning of untagged manifests is not available with Azure Basic tier. Upgrading to the Premium tier can help simplify manifests maintenance.

Provenance Attestations

The provenance attestations include facts about the build process, including details such as:

• Build timestamps.
• Build parameters and environment.
• Version control metadata.
• Source code details.
• Materials (files, scripts) consumed during the build.

An example of GitHub Actions workflow to remove untagged layers from the image is to set provenance = false in the Docker build and push step:

- name: Build and push
  uses: docker/build-push-action@v4
  with:
      context: .
      file: ./Dockerfile
      push: true
      
      tags: myacrio/images:latest
      cache-from: type=local,src=/tmp/.buildx-cache
      cache-to: type=local,dest=/tmp/.buildx-cache
      provenance: false
      

Cleaning Manifests From Azure Container Registry

• Login to Azure account and set proper subscription:

  az account set --subscription my-subscription
  

• Run the following command to list untagged manifests (with dry run parameter as we want to first check which manifests are going to be deleted).

az acr run --cmd 'acr purge --filter "repo_name:.*" --dry-run --ago 30d --untagged' --registry my_azure_container_registry --timeout 3600 /dev/null

• Once we are confident that corect manifests or tags will be deleted, run the same comanned without dry-run parameter to perfrom actual deletion of manifests.

az acr run --cmd 'acr purge --filter "repo_name:.*" --ago 30d --untagged' --registry my_azure_container_registry --timeout 3600 /dev/null

An action to automate manifests clean up in Azure Container Registry will be published on GitHub Actions marketplace soon. Feel free to reach out if you need early access before it’s officially published.