Auto Expiration Of Transient Quay.io Images

2 minute read

If you use a Quay.io repository to store Dockerfile images that can be regarded as transient, e.g. branch integration tests, then you can tag those Docker images with an expiration time so they are automatically deleted from Quay.

This helps avoid the cluttering up of a Quay.io repository with lots of images that will not be needed for any release or to be audit referenced in QMS documentation, e.g. as part of the testing of a story.

Dockerfile LABEL Tag

The Dockerfile LABEL command can be tagged with the argument quay.expires-after that specifies how long the image tag will remain in the repo.

The default is Never (case insensitive) but can be set to hours, days or weeks e.g. 1h, 2d, 3w - see here for more details.

A simple example of the Dockerfile LABEL command with this tag specified with 2 hours is as follows:

LABEL maintainer="me@acme.com" quay.expires-after=2h

A more useful method is having this expiration as an optional argument that can be specified by the build process:

ARG quay_expiration=never
LABEL maintainer="me@acme.com" quay.expires-after=${quay_expiration}

Manually Building the Docker Image

An example of the manual docker image build command passing through this argument value (2 hours) is as follows:

docker image build --build-arg quay_expiration=2h -t quay.io/acme/my-repo:0.0.1 .

Jenkins Docker Build

Typically the build process is managed via CI - in our case Jenkins. An example of the docker.build() method being used within a pipeline stage to set the value of the quay expiration argument is shown below. This is taken from a Microservice with integration tests which are currently regarded as transient and therefore the images are auto-expired after 1 hour.

dir("src/main/docker/acme-server") {
  container('dind') {
    script {
      docker.withRegistry('https://quay.io', 'acmeQuayIOCredentials') {
        def integrationTestsImage = docker.build("quay.io/acme/my-repo:${tag}",
            '--build-arg quay_expiration=1h .')
        integrationTestsImage.push()
      }
    }
  }
}

Display of Tags in Quay.IO If you have explicitly set an expiration tag for an image you will see this reflected in the image row as displayed in the Repository Tags page in Quay.io, e.g.:

expires in

Note that if you have the web page open the Expires value will also indicate if this expiration time has been passed, e.g. 17 hours ago as shown below.

expires in

All expired tags will be removed from the list if you refresh the page.

Note also that hovering over the Expires row value shows a pop up of the expiration date/time regardless of whether it has already expired.

Things to consider

Before you set the expiration tag (by default this will always be ‘Never’) for a particular set of images, consider the following:

  • Are the images pushed to Quay truly transient and will never be needed again ?
  • Typically ‘master’ build images will want to be kept permanently as will be part of a release so they should not have this tag overridden.
  • If images are needed for a defined period only, e.g. 1 week, 1 month, 6 months etc then the expiration tag can be set accordingly.
  • Some examples of images that probably can be auto-expired are:
    • Branch builds
    • Pull request checks as configured in GitHub (short expiry of e.g. 1 hour)
    • Snapshots (longer expiry of e.g. 1-6 months)