Chapter 15. Red Hat Quay auto-pruning overview Red Hat Quay administrators can set up auto-pruning policies on organizations and repositories; administrators can also set up auto-pruning policies at the registry level so that they apply to all organizations, including all newly created organizations. This feature allows for image tags to be automatically deleted within an organization or a repository based on specified criteria, which allows Red Hat Quay organization owners to stay below the storage quota by automatically pruning content. Currently, two policies have been added: Prune images by the number of tags . For this policy, when the actual number of tags exceeds the desired number of tags, the oldest tags are deleted by their 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 is dependent on your organization's settings. For more information, see Red Hat Quay garbage collection . Users can only configure one policy per namespace or repository; this can be done through the Red Hat Quay v2 UI. Policies can also be set by using the API endpoints through the command-line interface (CLI). 15.1. Prerequisites and limitations for auto-pruning 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. 15.2. Managing auto-pruning policies using the Red Hat Quay UI All auto-pruning policies, with the exception of a registry-wide auto pruning policy, are created using the Red Hat Quay v2 UI. This can be done after you have configured your Red Hat Quay config.yaml file to enable the auto-pruning feature and the v2 UI. Note This feature is not available when using the Red Hat Quay legacy UI. 15.2.1. Configuring the Red Hat Quay auto-pruning feature Use the following procedure to configure your Red Hat Quay config.yaml file to enable the auto-pruning feature. Prerequisites You have set FEATURE_UI_V2 to true in your config.yaml file. Procedure 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 # ... 15.2.2. Creating a registry-wide auto-pruning policy Registry-wide auto-pruning policies can be configured on new and existing organizations. This feature saves Red Hat Quay administrators time, effort, and storage by enforcing registry-wide rules. Red Hat Quay administrators must enable this feature by updating their config.yaml file through the inclusion of DEFAULT_NAMESPACE_AUTOPRUNE_POLICY configuration field, and one of number_of_tags or creation_date methods. Currently, this feature cannot be enabled by using the v2 UI or the API. Use the following procedure to create an auto-prune policy for your Red Hat Quay registry. Prerequisites You have enabled the FEATURE_AUTO_PRUNE feature. Procedure Update your config.yaml file to add the DEFAULT_NAMESPACE_AUTOPRUNE_POLICY configuration field: 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 1 # ... 1 In this scenario, two tags remain. 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 Restart your Red Hat Quay deployment. Optional. If you need to tag and push images to test this feature: Tag four sample images that will be pushed to a Red Hat Quay registry. For example: USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test2 USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test3 USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test4 Push the four sample images to the registry with auto-pruning enabled by entering the following commands: USD podman push <quay-server.example.com>/quayadmin/busybox:test USD podman push <quay-server.example.com>/<quayadmin>/busybox:test2 USD podman push <quay-server.example.com>/<quayadmin>/busybox:test3 USD podman push <quay-server.example.com>/<quayadmin>/busybox:test4 Check that there are four tags in the registry that you pushed the images to. 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. 15.2.3. Creating an auto-prune policy for an organization by using the Red Hat Quay v2 UI Use the following procedure to create an auto-prune policy for an organization using the Red Hat Quay v2 UI. Prerequisites You have enabled the FEATURE_AUTO_PRUNE feature. Procedure Tag four sample images, for example, busybox , that will be pushed to the repository with auto-pruning enabled. For example: USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test2 USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test3 USD podman tag docker.io/library/busybox <quay-server.example.com>/<quayadmin>/busybox:test4 Push the four sample images, for example, busybox , to the repository with auto-pruning enabled by entering the following commands: USD podman push <quay-server.example.com>/quayadmin/busybox:test USD podman push <quay-server.example.com>/<quayadmin>/busybox:test2 USD podman push <quay-server.example.com>/<quayadmin>/busybox:test3 USD podman push <quay-server.example.com>/<quayadmin>/busybox:test4 Check that there are four tags in your repository. On the Red Hat Quay v2 UI, click Organizations in the navigation pane. Select the name of an organization that you will apply the auto-pruning feature to, for example, test_organization . Click Settings . Click Auto-Prune Policies . For example: Click the drop down menu and select the desired policy, for example, By number of tags . 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 . 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 are marked for deletion starting from the tag's oldest creation date. 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 is dependent on your organization's settings. For more information, see Red Hat Quay garbage collection . 15.2.4. Creating an auto-prune policy for a namespace by using the Red Hat Quay API You can use Red Hat Quay API endpoints to manage auto-pruning policies for an namespace. Prerequisites You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file. You have created an OAuth access token. You have logged into Red Hat Quay. Procedure Enter the following POST command create a new policy that limits the number of tags allowed in an organization: USD 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 can set tags to expire for a specified time after their creation date: USD 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"} Attempting to create multiple policies returns the following error: {"detail": "Policy for this namespace already exists, delete existing to create new policy", "error_message": "Policy for this namespace already exists, delete existing to create new policy", "error_type": "invalid_request", "title": "invalid_request", "type": "http://<quay-server.example.com>/api/v1/error/invalid_request", "status": 400} Check your auto-prune policy by entering the following command: USD curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/ Example output {"policies": [{"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e", "method": "creation_date", "value": "7d"}]} You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. USD curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/73d64f05-d587-42d9-af6d-e726a4a80d6e 15.2.5. Creating an auto-prune policy for a namespace for the current user by using the API You can use Red Hat Quay API endpoints to manage auto-pruning policies for your account. Note The use of /user/ in the following commands represents the user that is currently logged into Red Hat Quay. Prerequisites You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file. You have created an OAuth access token. You have logged into Red Hat Quay. Procedure Enter the following POST command create a new policy that limits the number of tags for the current user: USD 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"} Check your auto-prune policy by entering the following command: USD curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/<user>/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859 Alternatively, you can include the UUID: USD curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/<user>/autoprunepolicy/ Example output {"policies": [{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859", "method": "number_of_tags", "value": 10}]} You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. USD 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"} 15.2.6. Creating an auto-prune policy for a repository using the Red Hat Quay v2 UI Use the following procedure to create an auto-prune policy for a repository using the Red Hat Quay v2 UI. Prerequisites You have enabled the FEATURE_AUTO_PRUNE feature. Procedure Tag four sample images, for example, busybox , that will be pushed to the repository with auto-pruning enabled. For example: USD podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test USD podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test2 USD podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test3 USD podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test4 Push the four sample images, for example, busybox , to the repository with auto-pruning enabled by entering the following commands: USD podman push <quay-server.example.com>/<organization_name>/<repository_name>:test USD podman push <quay-server.example.com>/<organization_name>/<repository_name>:test2 USD podman push <quay-server.example.com>/<organization_name>/<repository_name>:test3 USD podman push <quay-server.example.com>/<organization_name>/<repository_name>:test4 Check that there are four tags in your repository. On the Red Hat Quay v2 UI, click Repository in the navigation pane. Select the name of an organization that you will apply the auto-pruning feature to, for example, <organization_name>/<repository_name> . Click Settings . Click Repository Auto-Prune Policies . Click the drop down menu and select the desired policy, for example, By number of tags . 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 . 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 are marked for deletion starting from the tag's oldest creation date. 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 is dependent on your organization's settings. For more information, see Red Hat Quay garbage collection . 15.2.7. Creating an auto-prune policy for a repository using the Red Hat Quay API You can use Red Hat Quay API endpoints to manage auto-pruning policies for an repository. Prerequisites You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file. You have created an OAuth access token. You have logged into Red Hat Quay. Procedure Enter the following POST command create a new policy that limits the number of tags allowed in an organization: USD 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 can set tags to expire for a specified time after their creation date: USD 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"} Attempting to create multiple policies returns the following error: {"detail": "Policy for this namespace already exists, delete existing to create new policy", "error_message": "Policy for this namespace already exists, delete existing to create new policy", "error_type": "invalid_request", "title": "invalid_request", "type": "http://quay-server.example.com/api/v1/error/invalid_request", "status": 400} Check your auto-prune policy by entering the following command: USD 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: USD 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}]} You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. USD 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"} 15.2.8. Creating an auto-prune policy on a repository for a user with the API You can use Red Hat Quay API endpoints to manage auto-pruning policies on a repository for user accounts that are not your own, so long as you have admin privileges on the repository. Prerequisites You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file. 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 Enter the following POST command create a new policy that limits the number of tags for the current user: USD 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/<user_account>/<user_repository>/autoprunepolicy/ Example output {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"} Check your auto-prune policy by entering the following command: USD 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: USD 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 {"policies": [{"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7", "method": "number_of_tags", "value": 2}]} You can delete the auto-prune policy by entering the following command. Note that deleting the policy requires the UUID. USD curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/7726f79c-cbc7-490e-98dd-becdc6fefce7 Example output {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}

Commands:
FEATURE_AUTO_PRUNE: true
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY: method: number_of_tags value: 2 1
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY: method: creation_date value: 5d
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
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
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
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
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/
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/
uuid: 73d64f05-d587-42d9-af6d-e726a4a80d6e
detail: Policy for this namespace already exists, delete existing to create new policy
error_message: Policy for this namespace already exists, delete existing to create new policy
error_type: invalid_request
title: invalid_request
type: http://<quay-server.example.com>/api/v1/error/invalid_request
status: 400
curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/
{"policies": [{"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e", "method": "creation_date", "value": "7d"}]}
curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/organization/<organization_name>/autoprunepolicy/73d64f05-d587-42d9-af6d-e726a4a80d6e
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/
uuid: 8c03f995-ca6f-4928-b98d-d75ed8c14859
curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/<user>/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859
curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/<user>/autoprunepolicy/
{"policies": [{"uuid": "8c03f995-ca6f-4928-b98d-d75ed8c14859", "method": "number_of_tags", "value": 10}]}
curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/<user>/autoprunepolicy/8c03f995-ca6f-4928-b98d-d75ed8c14859
uuid: 8c03f995-ca6f-4928-b98d-d75ed8c14859
podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test
podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test2
podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test3
podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/<repository_name>:test4
podman push <quay-server.example.com>/<organization_name>/<repository_name>:test
podman push <quay-server.example.com>/<organization_name>/<repository_name>:test2
podman push <quay-server.example.com>/<organization_name>/<repository_name>:test3
podman push <quay-server.example.com>/<organization_name>/<repository_name>:test4
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/
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/
uuid: ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7
detail: Policy for this namespace already exists, delete existing to create new policy
error_message: Policy for this namespace already exists, delete existing to create new policy
error_type: invalid_request
title: invalid_request
type: http://quay-server.example.com/api/v1/error/invalid_request
status: 400
curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/autoprunepolicy/
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
{"policies": [{"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7", "method": "number_of_tags", "value": 10}]}
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
uuid: ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7
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/<user_account>/<user_repository>/autoprunepolicy/
uuid: 7726f79c-cbc7-490e-98dd-becdc6fefce7
curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/repository/<user_account>/<user_repository>/autoprunepolicy/
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
{"policies": [{"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7", "method": "number_of_tags", "value": 2}]}
curl -X DELETE -H "Authorization: Bearer <access_token>" http://<quay-server.example.com>/api/v1/user/autoprunepolicy/7726f79c-cbc7-490e-98dd-becdc6fefce7
uuid: 7726f79c-cbc7-490e-98dd-becdc6fefce7