Automatic tag deletion for Docker registries

Moritz Rinow — Tue, 13 May 2025 15:17:09 +0000

Introduction

Docker registries are essential nowadays in a world of containerized workloads. Want to run your app on Kubernetes? You need to push it to a registry first. If you don't want to pay for a managed, private registry service, you self-host your own.

The biggest pain point of Docker registries is storage. If you choose to store registry data on a local disk, you are limited by capacity.
If you choose to use cloud object-storage (Azure, S3, etc.), you are limited by costs.

Over time, registries accumulate a lot of garbage in the form of blobs referenced by old images that are not needed anymore. Many registry implementations, such as CNCF Distribution, offer garbage-collection mechanisms to delete unreferenced blobs and free up storage space. However, for that to happen, old images (tags) referencing them have to be deleted first.

There are implementations like Harbor, which offer native retention policies for tags. However, if you host a registry like CNCF Distribution, you need additional tooling to automatically delete tags.

Regmaid

Regmaid is a simple CLI tool to enforce tag retention policies on Docker registries. It works entirely by communicating with the Docker Registry HTTP API V2, making the functionality independent of registry implementation and storage backend.

How does it work?

Regmaid inspects every image manifest behind every tag of a target repository to figure out the age of all images. It then deletes all tags matching a user-defined retention policy, allowing you to keep a min/max amount of tags and delete tags older than a specified period of time.

Example

Define your registries and policies in a regmaid.yaml file:

dockerCreds: false # Use locally cached credentials from `docker login` 

registries:
  - name: dev
    host: internal.registry.com
    username: user
    password: password

policies:
  - name: example-app-dev
    registry: dev
    repository: example-app # Policies always target a single repository
    match: *-dev # Match tags ending with '-dev'
    retention: 30d # Delete tags older than 30 days
    keep: 5 # Always keep at least newest 5 tags

If you do not specify retention, the value of keep represents the max. amount of tags that will be kept.

Regmaid can be installed via Go:

go install github.com/moritzrinow/regmaid@latest

Run Regmaid with dry-run to confirm it's working:

regmaid -c regmaid.yaml --dry-run

Regmaid will output all tags found eligible for deletion:

Processing policy "example-app-dev"...
Finished processing policy "example-app-dev"
Policy "example-app-dev" found 1/11 tags eligible for deletion:
0.1.0-dev (sha256:db38eb0ad0b317eba25b2d229d7b2af571961f6f2253bd223a11d48135e279fe) (55d)

Alternatively, Regmaid can also be run with Docker:

docker run -it -v /path/to/regmaid.yaml:/etc/regmaid/regmaid.yaml ghcr.io/moritzrinow/regmaid:latest

After processing all policies, Regmaid will ask you to confirm the tag deletion. This can be skipped by providing the parameter --yes.

Automation