Adds multiple auto-pruning policies info (quay#1119)

Co-authored-by: Steven Smith <[email protected]>

Author: stevsmit

images/auto-prune-policies-page.png

@@ -33,6 +33,10 @@ The policy configuration that is to be applied to the user namespace
 _required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
 _required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-createOrganizationAutoPrunePolicy.adoc

@@ -30,9 +30,13 @@ The policy configuration that is to be applied to the user namespace
 |===
 |Name|Description|Schema
 |**method** + 
-_optional_|The method to use for pruning tags (number_of_tags, creation_date)|string
+_required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
-_optional_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+_required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-createRepositoryAutoPrunePolicy.adoc

@@ -23,6 +23,10 @@ The policy configuration that is to be applied to the user namespace
 _required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
 _required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-createUserAutoPrunePolicy.adoc

@@ -16,10 +16,10 @@ Updates the auto-prune policy for the organization
 [options="header", width=100%, cols=".^2a,.^3a,.^9a,.^4a"]
 |===
 |Type|Name|Description|Schema
-|path|**orgname** + 
-_required_|The name of the organization|string
 |path|**policy_uuid** + 
 _required_|The unique ID of the policy|string
+|path|**orgname** + 
+_required_|The name of the organization|string
 |===
 
 
@@ -35,6 +35,10 @@ The policy configuration that is to be applied to the user namespace
 _required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
 _required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-updateOrganizationAutoPrunePolicy.adoc

@@ -32,9 +32,13 @@ The policy configuration that is to be applied to the user namespace
 |===
 |Name|Description|Schema
 |**method** + 
-_optional_|The method to use for pruning tags (number_of_tags, creation_date)|string
+_required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
-_optional_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+_required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-updateRepositoryAutoPrunePolicy.adoc

@@ -33,6 +33,10 @@ The policy configuration that is to be applied to the user namespace
 _required_|The method to use for pruning tags (number_of_tags, creation_date)|string
 |**value** + 
 _required_|The value to use for the pruning method (number of tags e.g. 10, time delta e.g. 7d (7 days))|
+|**tagPattern** + 
+_optional_|Tags only matching this pattern will be pruned|string
+|**tagPatternMatches** + 
+_optional_|Determine whether pruned tags should or should not match the tagPattern|boolean
 |===
 
 

modules/api-policy-updateUserAutoPrunePolicy.adoc

@@ -2,7 +2,7 @@
 [id="managing-namespace-auto-pruning-policies"]
 = Managing auto-pruning policies using the {productname} UI
 
-All auto-pruning policies, with the exception of a registry-wide auto pruning policy, are created using the {productname} v2 UI. This can be done after you have configured your {productname} `config.yaml` file to enable the auto-pruning feature and the v2 UI.
+All auto-pruning policies, with the exception of a registry-wide auto pruning policy, are created using the {productname} v2 UI or by using the API. This can be done after you have configured your {productname} `config.yaml` file to enable the auto-pruning feature and the v2 UI.
 
 [NOTE]
 ====
@@ -191,6 +191,10 @@ image:auto-prune-policies-page.png[Auto-Prune Policies page]
 
 . 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*.
 
+. Optional. To prune only tags that match the given regex pattern, 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.*`. To prune a specific image, you can enter `^test1$`. 
+
+. Optional. You can create a second auto-prune policy by clicking *Add Policy* and entering the required information. 
+
 . Click *Save*. A notification that your auto-prune policy has been updated appears. 
 
 .Verification
@@ -212,7 +216,7 @@ You can use {productname} API endpoints to manage auto-pruning policies for an n
 
 .Procedure 
 
-. Enter the following `POST` command create a new policy that limits the number of tags allowed in an organization:
+. Enter the following link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#createorganizationautoprunepolicy[`POST /api/v1/organization/{orgname}/autoprunepolicy/`] command create a new policy that limits the number of tags allowed in an organization:
 +
 [source,terminal]
 ----
@@ -232,13 +236,43 @@ $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: appli
 ----
 {"uuid": "73d64f05-d587-42d9-af6d-e726a4a80d6e"}
 ----
+
+. 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:
++
+[source,terminal]
+----
+$ 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/"
+----
++
+.Example output
 +
-Attempting to create multiple policies returns the following error:
+[source,terminal]
+----
+{"uuid": "ebf7448b-93c3-4f14-bf2f-25aa6857c7b0"}
+----
+
+. You can update your organization's auto-prune policy by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#updateorganizationautoprunepolicy[`PUT /api/v1/organization/{orgname}/autoprunepolicy/{policy_uuid}`] command. For example:
 +
 [source,terminal]
 ----
-{"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 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.
 
 . Check your auto-prune policy by entering the following command:
 +
@@ -254,7 +288,7 @@ $ curl -X GET -H "Authorization: Bearer <access_token>" http://<quay-server.exam
 {"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.
+. You can delete the auto-prune policy for your organization by entering the following command. Note that deleting the policy requires the UUID.
 +
 [source,terminal]
 ----
@@ -397,6 +431,10 @@ $ podman push <quay-server.example.com>/<organization_name>/<repository_name>:te
 
 . 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*.
 
+. Optional. To prune only tags that match the given regex pattern, 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.*`. To prune a specific image, you can enter `^test1$`. 
+
+. Optional. You can create a second auto-prune policy by clicking *Add Policy* and entering the required information. 
+
 . Click *Save*. A notification that your auto-prune policy has been updated appears.
 
 .Verification
@@ -418,7 +456,7 @@ You can use {productname} API endpoints to manage auto-pruning policies for an r
 
 .Procedure
 
-. Enter the following `POST` command create a new policy that limits the number of tags allowed in an organization:
+. Enter the following link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#updateorganizationautoprunepolicy[`POST /api/v1/repository/{repository}/autoprunepolicy/`] command create a new policy that limits the number of tags allowed in an organization:
 +
 [source,terminal]
 ----
@@ -438,14 +476,48 @@ $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: appli
 ----
 {"uuid": "ce2bdcc0-ced2-4a1a-ac36-78a9c1bed8c7"}
 ----
+
+. 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:
++
+[source,terminal]
+----
+$ curl -X POST \
+  -H "Authorization: Bearer <access_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "method": "<creation_date>",
+    "value": "<7d>",
+    "tagPattern": "<^test.>*",
+    "tagPatternMatches": <true>
+  }' \
+  "https://<quay-server.example.com>/api/v1/repository/<organization_name>/<repository_name>/<tag_name>/autoprunepolicy/"
+----
 +
-Attempting to create multiple policies returns the following error:
+.Example output
 +
 [source,terminal]
 ----
-{"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}
+{"uuid": "b53d8d3f-2e73-40e7-96ff-736d372cd5ef"}
 ----
 
+. You can update your policy for the repository by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#updaterepositoryautoprunepolicy[`PUT /api/v1/repository/{repository}/autoprunepolicy/{policy_uuid}`] command and passing in the UUID. For example:
++
+[source,terminal]
+----
+$ 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.
+
 . Check your auto-prune policy by entering the following command:
 +
 [source,terminal]
@@ -495,7 +567,7 @@ You can use {productname} API endpoints to manage auto-pruning policies on a rep
 
 .Procedure 
 
-. Enter the following `POST` command create a new policy that limits the number of tags for the current user:
+. Enter the following link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#createuserautoprunepolicy[`POST /api/v1/user/autoprunepolicy/`] command create a new policy that limits the number of tags for the current user:
 +
 [source,terminal]
 ----
@@ -509,6 +581,43 @@ $ curl -X POST -H "Authorization: Bearer <access_token>" -H "Content-Type: appli
 {"uuid": "7726f79c-cbc7-490e-98dd-becdc6fefce7"}
 ----
 
+. 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:
++
+[source,terminal]
+----
+$ 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/user/autoprunepolicy/"
+----
++
+.Example output
++
+[source,terminal]
+----
+{"uuid": "b3797bcd-de72-4b71-9b1e-726dabc971be"}
+----
+
+. You can update your policy for the current user by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#updateuserautoprunepolicy[`PUT /api/v1/user/autoprunepolicy/{policy_uuid}`] command. For example:
++
+[source,terminal]
+----
+$ 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/user/autoprunepolicy/<uuid>"
+----
++
+Updating a policy does not return output in the CLI.
+
 . Check your auto-prune policy by entering the following command:
 +
 [source,terminal]

modules/managing-namespace-auto-pruning-policies.adoc

@@ -2,25 +2,30 @@
 [id="red-hat-quay-namespace-auto-pruning-overview"]
 = {productname} auto-pruning overview
 
-{productname} 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 {productname} organization owners to stay below the storage quota by automatically pruning content.
+{productname} administrators can set up multiple 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 {productname} 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 {productname} 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 link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#garbage-collection[{productname} garbage collection]. 
+After tags are automatically pruned, they go into the {productname} 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 link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/manage_red_hat_quay/index#garbage-collection[{productname} garbage collection]. 
 
-Users can only configure one policy per namespace or repository; this can be done through the {productname} v2 UI. Policies can also be set by using the API endpoints through the command-line interface (CLI). 
+Users can configure multiple policies per namespace or repository; this can be done through the {productname} v2 UI. Policies can also be set by using the API endpoints through the command-line interface (CLI). 
 
 [id="prerequisites-limitations-namespace-autopruning"]
-== Prerequisites and limitations for auto-pruning 
+== Prerequisites and limitations for auto-pruning and multiple policies
 
 The following prerequisites and limitations apply to the auto-pruning feature:
 
 * Auto-pruning is not available when using the {productname} 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.
+* 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 for 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.