SupportConsoleDevelopersStart a trialContact

Chapter 14. Red Hat Quay auto-pruning overview

Red Hat Quay auto-pruning deletes image tags in organizations and repositories by tag count or age so that owners can stay under storage quotas. You can configure policies at the organization, repository, or registry level.

Red Hat Quay administrators can configure multiple auto-pruning policies on organizations and repositories. Administrators can also configure auto-pruning policies at the registry level so that they apply to all organizations, including newly created organizations.

Currently, two policies are available:

  • Prune images by the number of tags. For this policy, when the actual number of tags exceeds the desired number of tags, the auto-pruner deletes the oldest tags by creation date until the desired number of tags is achieved.
  • Prune image tags by creation date. For this policy, any tags with a creation date older than the given time span, for example, 10 days, are deleted.

After tags are automatically pruned, they go into the Red Hat Quay time machine, or the amount of time after a tag is deleted that the tag is accessible before being garbage collected. The expiration time of an image tag depends on your organization’s settings.

Users can configure multiple policies per namespace or repository through the Red Hat Quay v2 UI. Policies can also be set by using the API endpoints through the command-line interface (CLI).

Review these prerequisites and limitations before you configure Red Hat Quay auto-pruning policies for organizations or repositories.

The following prerequisites and limitations apply to the auto-pruning feature:

  • Auto-pruning is not available when using the Red Hat Quay legacy UI. You must use the v2 UI to create, view, or modify auto-pruning policies.
  • Auto-pruning is only supported in databases that support the FOR UPDATE SKIP LOCKED SQL command.
  • Auto-pruning is unavailable on mirrored repositories and read-only repositories.

  • If you are configuring multiple auto-prune policies, rules are processed without particular order, and individual result sets are processed immediately before moving on to the next rule.

    • For example, if an image is already subject to garbage collection by one rule, it cannot be excluded from pruning by another rule.
  • If you have both an auto-pruning policy for an organization and a repository, the auto-pruning policies set at the organization level are executed first.

14.2. Regular expressions with auto-pruning
Copy link

You can use regular expressions with organization- and repository-level auto-pruning policies in Red Hat Quay to match a subset of tags for removal.

Consider the following when using regular expressions with the auto-pruning feature:

  • Regular expressions are optional.
  • If a regular expression is not provided, the auto-pruner defaults to pruning all image tags in the organization or the repository. These are user-supplied and must be protected against ReDoS attacks.
  • Registry-wide policies do not currently support regular expressions. Only organization- and repository-level auto-pruning policies support regular expressions.
  • Regular expressions can be configured to prune images that either do, or do not, match the provided regex pattern.

Some of the following procedures provide example auto-pruning policies that use regular expressions that you can use as a reference when creating an auto-prune policy.

You can manage most Red Hat Quay auto-pruning policies from the v2 UI or the API after you enable auto-pruning and the v2 UI in your config.yaml file. Registry-wide policies are configured only in the config.yaml file.

14.3.1. Enabling image pull activity tracking
Copy link

To enable image pull activity tracking in Red Hat Quay, you can set FEATURE_IMAGE_PULL_STATS in your config.yaml file and configure Redis for pull metrics.

Procedure

  1. In your Red Hat Quay config.yaml file, set FEATURE_IMAGE_PULL_STATS: true. For example: 

    # ...
FEATURE_IMAGE_PULL_STATS: true
REDIS_FLUSH_INTERVAL_SECONDS: 30
PULL_METRICS_REDIS:
    host: <redis_host>
    password: <redis_password>
    port: 6379
    db: 1
# ...

    where:

    FEATURE_IMAGE_PULL_STATS
    Specifies whether image pull tracking activity is enabled.
    REDIS_FLUSH_INTERVAL_SECONDS
    Specifies the time, in seconds, at which the Redis flush worker clears old data. Shorter intervals keep data fresher and help prevent Redis from bloating, while longer intervals reduce flush frequency.
    PULL_METRICS_REDIS
    Specifies the connection settings for the Redis database used to store image pull metrics.
  2. Restart your Red Hat Quay deployment.

Verification

  1. Push an image to your registry by entering the following command. Following this step, you can use your browser to see the tagged image in your repository. 

    $ podman push <quay-server.example.com>/<organization>/<image>:<tag>

  2. Pull the image from your Red Hat Quay registry by entering the following command: 

    $ podman pull <quay-server.example.com>/<organization>/<image>:<tag>
  3. On the Red Hat Quay UI, navigate to Repositories, and then click the name of your repository.

  4. Click Tags. The Last Pulled and Pull Count categories show you information about when the image was last pulled, and how many times it has been pulled, respectively. For example:

    Image pull statistics

To enable auto-pruning in Red Hat Quay, you can set FEATURE_AUTO_PRUNE to true in your config.yaml file.

Prerequisites

  • You have set FEATURE_UI_V2 to true in your config.yaml file.

Procedure

  1. In your Red Hat Quay config.yaml file, add and set the FEATURE_AUTO_PRUNE environment variable to true. For example: 

    # ...
FEATURE_AUTO_PRUNE: true
# ...

To apply an auto-prune policy to all organizations in a Red Hat Quay registry, you can configure DEFAULT_NAMESPACE_AUTOPRUNE_POLICY in your config.yaml file.

Registry-wide auto-pruning policies can apply to new and existing organizations. Red Hat Quay administrators enable this feature by adding the DEFAULT_NAMESPACE_AUTOPRUNE_POLICY configuration field with either the number_of_tags or creation_date method. Currently, you cannot enable this feature by using the v2 UI or the API.

Prerequisites

  • You have enabled the FEATURE_AUTO_PRUNE feature.

Procedure

  1. Update your config.yaml file to add the DEFAULT_NAMESPACE_AUTOPRUNE_POLICY configuration field:

    1. To set the policy method to remove the oldest tags by their creation date until the number of tags provided is left, use the number_of_tags method: 

      # ...
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY:
  method: number_of_tags
  value: 2
# ...

      where: value:: Specifies the number of tags to keep. In this example, two tags remain.

    2. To set the policy method to remove tags with a creation date older than the provided time span, for example, 5d, use the creation_date method: 

      DEFAULT_NAMESPACE_AUTOPRUNE_POLICY:
  method: creation_date
  value: 5d
  2. Restart your Red Hat Quay deployment.

  3. Optional. If you need to tag and push images to test this feature:

    1. Tag four sample images that you push to a Red Hat Quay registry. For example: 

      $ podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test
       
      $ podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test2
       
      $ podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test3
       
      $ podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test4

    2. Push the four sample images to the registry with auto-pruning enabled by entering the following commands: 

      $ podman push <quay-server.example.com>/quayadmin/busybox:test
       
      $ podman push <quay-server.example.com>/<quayadmin>/busybox:test2
       
      $ podman push <quay-server.example.com>/<quayadmin>/busybox:test3
       
      $ podman push <quay-server.example.com>/<quayadmin>/busybox:test4
  4. Check that the registry that you pushed the images to shows four tags.
  5. By default, the auto-pruner worker at the registry level runs every 24 hours. After 24 hours, the two oldest image tags are removed, leaving the test3 and test4 tags if you followed these instructions. Check your Red Hat Quay organization to ensure that the two oldest tags were removed.

To create an organization auto-prune policy in Red Hat Quay, you can configure Auto-Prune Policies on the organization Settings page in the v2 UI.

Prerequisites

  • You have enabled the FEATURE_AUTO_PRUNE feature.
  • Your organization has image tags that have been pushed to it.

Procedure

  1. On the Red Hat Quay v2 UI, click Organizations in the navigation pane.
  2. Select the name of an organization to which you apply the auto-pruning feature, for example, test_organization.
  3. Click Settings.

  4. Click Auto-Prune Policies. For example:

    Auto-Prune Policies page

  5. Click the drop-down menu and select the desired policy, for example, By number of tags.
  6. Select the desired number of tags to keep. By default, this is set at 20 tags. For this example, the number of tags to keep is set at 3.

  7. Optional. With the introduction of regular expressions, you are provided the following options to fine-tune your auto-pruning policy:

    • Match: When selecting this option, the auto-pruner prunes all tags that match the given regex pattern.

    • Does not match: When selecting this option, the auto-pruner prunes all tags that do not match the regex pattern.

      If you do not select an option, the auto-pruner defaults to pruning all image tags.

      For this example, click the Tag pattern box and select match. In the regex box, enter a pattern to match tags against. For example, to automatically prune all test tags, enter ^test.*.

  8. Optional. You can create a second auto-prune policy by clicking Add Policy and entering the required information.

  9. Click Save. A notification that your auto-prune policy has been updated appears.

    With this example, the organization is configured to keep the three latest tags that are named ^test.*.

Verification

  • Navigate to the Tags page of your Organization’s repository. After a few minutes, the auto-pruner worker removes tags that no longer fit within the established criteria. In this example, it removes the busybox:test tag, and keeps the busybox:test2, busybox:test3, and busybox:test4 tag.

    After tags are automatically pruned, they go into the Red Hat Quay time machine, or the amount of time after a tag is deleted that the tag is accessible before being garbage collected. The expiration time of an image tag depends on your organization’s settings.

To create, update, view, or delete an organization auto-prune policy in Red Hat Quay, you can use the organization autoprunepolicy API endpoints.

Prerequisites

  • You have created an OAuth access token.
  • You have logged into Red Hat Quay.

Procedure

  1. Enter the following POST /api/v1/organization/<organization_name>/autoprunepolicy/ command to create a new policy that limits the number of tags allowed in an organization: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/

    Alternatively, you can set tags to expire for a specified time after their creation date: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{
"method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/

    Example output:

    {"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e"}

  2. Optional. You can add an additional policy to an organization and pass in the tagPattern and tagPatternMatches fields to prune only tags that match the given regex pattern. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "creation_date",
    "value": "7d",
    "tagPattern": "^v*",
    "tagPatternMatches": <true>
  }' \
  "https://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/"

    where:

    tagPatternMatches

    Specifies whether tags that match the regex pattern are pruned. Set to true to prune matching tags. In this example, tags that match ^v* are pruned.

    Example output:

    {"uuid": "ebf7448b-93c3-4f14-bf2f-25aa6857c7b0"}

  3. You can update your organization’s auto-prune policy by using the PUT /api/v1/organization/<organization_name>/autoprunepolicy/<policy_uuid> command. For example: 

    $ curl -X PUT   -H "Authorization: Bearer <bearer_token>"   -H "Content-Type: application/json"   -d '{
    "method": "creation_date",
    "value": "4d",
    "tagPattern": "^v*",
    "tagPatternMatches": true
  }'   "<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/<uuid>"

    This command does not return output. Continue to the next step.

  4. Check your auto-prune policy by entering the following command: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/

    Example output:

    {"policies": [{"uuid": "ebf7448b-93c3-4f14-bf2f-25aa6857c7b0", "method": "creation_date", "value": "4d", "tagPattern": "^v*", "tagPatternMatches": true}, {"uuid": "da4d0ad7-3c2d-4be8-af63-9c51f9a501bc", "method": "number_of_tags", "value": 10, "tagPattern": null, "tagPatternMatches": true}, {"uuid": "17b9fd96-1537-4462-a830-7f53b43f94c2", "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true}]}

  5. You can delete the auto-prune policy for your organization by entering the following command. Note that deleting the policy requires the UUID. 

    $ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/73d64f05-d587-42d9-af6d-e726a4a80d6e

To manage auto-prune policies for your own user namespace in Red Hat Quay, you can use the /api/v1/user/autoprunepolicy/ API endpoints.

Note

The use of /user/ in the following commands represents the user that is currently logged into Red Hat Quay.

Prerequisites

  • You have created an OAuth access token.
  • You have logged into Red Hat Quay.

Procedure

  1. Enter the following POST command to create a new policy that limits the number of tags for the current user: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags", "value": 10}' http://<quay-server.example.com>/api/v1/user/autoprunepolicy/

    Example output

    {"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}

  2. Check your auto-prune policy by entering the following command: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/

    Alternatively, you can include the UUID: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859

    Example output

    {"policies": [{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859", "method": "number_of_tags", "value": 10}]}

  3. You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. 

    $ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859

    Example output

    {"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859"}

To create a repository auto-prune policy in Red Hat Quay, you can configure Repository Auto-Prune Policies on the repository Settings page in the v2 UI.

Prerequisites

  • You have enabled the FEATURE_AUTO_PRUNE feature.
  • You have pushed image tags to your repository.

Procedure

  1. On the Red Hat Quay v2 UI, click Repository in the navigation pane.
  2. Select the name of a repository to which you apply the auto-pruning feature, for example, <organization_name>/<repository_name>.
  3. Click Settings.
  4. Click Repository Auto-Prune Policies.
  5. Click the drop-down menu and select the desired policy, for example, By age of tags.
  6. Set a time, for example, 5 and an interval, for example minutes to delete tags older than the specified time frame. For this example, tags older than 5 minutes are marked for deletion.

  7. Optional. With the introduction of regular expressions, you are provided the following options to fine-tune your auto-pruning policy:

    • Match: When selecting this option, the auto-pruner prunes all tags that match the given regex pattern.

    • Does not match: When selecting this option, the auto-pruner prunes all tags that do not match the regex pattern.

      If you do not select an option, the auto-pruner defaults to pruning all image tags.

      For this example, click the Tag pattern box and select Does not match. In the regex box, enter a pattern to match tags against. For example, to automatically prune all tags that do not match the test tag, enter ^test.*.

  8. Optional. You can create a second auto-prune policy by clicking Add Policy and entering the required information.
  9. Click Save. A notification that your auto-prune policy has been updated appears.

Verification

  • Navigate to the Tags page of your Organization’s repository. With this example, Tags that are older than 5 minutes that do not match the ^test.* regex tag are automatically pruned when the pruner runs.

    After tags are automatically pruned, they go into the Red Hat Quay time machine, or the amount of time after a tag is deleted that the tag is accessible before being garbage collected. The expiration time of an image tag depends on your organization’s settings.

To create, update, view, or delete a repository auto-prune policy in Red Hat Quay, you can use the repository autoprunepolicy API endpoints.

Prerequisites

  • You have created an OAuth access token.
  • You have logged into Red Hat Quay.

Procedure

  1. Enter the following POST /api/v1/repository/<repository>/autoprunepolicy/ command to create a new policy that limits the number of tags allowed in a repository: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/

    Alternatively, you can set tags to expire for a specified time after their creation date: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "creation_date", "value": "7d"}' http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/

    Example output

    {"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}

  2. Optional. You can add an additional policy and pass in the tagPattern and tagPatternMatches fields to prune only tags that match the given regex pattern. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "creation_date",
    "value": "7d",
    "tagPattern": "^test.",
    "tagPatternMatches": false
  }' \
  "https://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/"

    Where:

    tagPatternMatches
    Specifies that the false value prunes tags that do not match the given regex pattern. In this example, all tags except those that match ^test. are pruned.

  3. You can update your policy for the repository by using the PUT /api/v1/repository/<repository>/autoprunepolicy/<policy_uuid> command and passing in the UUID. For example: 

    $ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "number_of_tags",
    "value": "5",
    "tagPattern": "^test.*",
    "tagPatternMatches": true
  }' \
  "https://quay-server.example.com/api/v1/repository/<namespace>/<repo_name>/autoprunepolicy/<uuid>"

    This command does not return output. Continue to the next step to check your auto-prune policy.

  4. Check your auto-prune policy by entering the following command: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/

    Alternatively, you can include the UUID: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7

    Example output

    {"policies": [{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7", "method": "number_of_tags", "value": 10}]}

  5. You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. 

    $ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7

    Example output

    {"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}

To manage auto-prune policies on another user repository in Red Hat Quay, you can use the repository autoprunepolicy API endpoints when you have admin privileges.

Prerequisites

  • You have created an OAuth access token.
  • You have logged into Red Hat Quay.
  • You have admin privileges on the repository that you are creating the policy for.

Procedure

  1. Enter the following POST /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/ command to create a new policy that limits the number of tags for the user: 

    $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d '{"method": "number_of_tags","value": 2}' https://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/

    Example output

    {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}

  2. Optional. You can add an additional policy for the current user and pass in the tagPattern and tagPatternMatches fields to prune only tags that match the given regex pattern. For example: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "creation_date",
    "value": "7d",
    "tagPattern": "^v*",
    "tagPatternMatches": true
  }' \
  "http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/"

    Example output

    {"uuid": "b3797bcd-de72-4b71-9b1e-726dabc971be"}

  3. You can update your policy for the current user by using the PUT /api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid> command. For example: 

    $ curl -X PUT   -H "Authorization: Bearer <bearer_token>"   -H "Content-Type: application/json"   -d '{
    "method": "creation_date",
    "value": "4d",
    "tagPattern": "^test.",
    "tagPatternMatches": true
  }'   "https://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid>"

    Updating a policy does not return output in the CLI.

  4. Check your auto-prune policy by entering the following command: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/

    Alternatively, you can include the UUID: 

    $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/7726f79c-cbc7-490e-98dd-becdc6fefce7

    Example output

    {"uuid": "81ee77ec-496a-4a0a-9241-eca49437d15b", "method": "creation_date", "value": "7d", "tagPattern": "^v*", "tagPatternMatches": true}

  5. You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. 

    $ curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/<policy_uuid>

    Example output

    {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top