New auto-pruning modules (#16)

Deprecate the auto_prune_method and auto_prune_value parameters in favor of the new quay_organization_prune and quay_repository_prune modules. --------- Co-authored-by: Hervé Quatremain <[email protected]>
redhat-cop · Nov 23, 2024 · 5a97e57 · 5a97e57
1 parent 8f51f71
commit 5a97e57
Show file tree

Hide file tree

Showing 31 changed files with 1,430 additions and 71 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4,6 +4,25 @@ Quay Container Registry Collection Release Notes
 
 .. contents:: Topics
 
+v2.4.0
+======
+
+Release Summary
+---------------
+
+New ``infra.quay_configuration.quay_organization_prune`` and ``infra.quay_configuration.quay_repository_prune`` modules.
+
+Deprecated Features
+-------------------
+
+- The ``auto_prune_method`` and ``auto_prune_value`` parameters of the ``infra.quay_configuration.quay_organization`` and ``infra.quay_configuration.quay_repository`` modules are deprecated in favor of the new``infra.quay_configuration.quay_organization_prune`` and ``infra.quay_configuration.quay_repository_prune`` modules.
+
+New Modules
+-----------
+
+- infra.quay_configuration.quay_organization_prune - Manage auto-pruning policies for organizations and user namespaces
+- infra.quay_configuration.quay_repository_prune - Manage auto-pruning policies for repositories
+
 v2.2.0
 ======
 

diff --git a/README.md b/README.md
@@ -30,10 +30,12 @@ Name | Description
 `quay_message` |            Manage Quay Container Registry global messages
 `quay_notification` |       Manage Quay Container Registry repository notifications
 `quay_organization` |       Manage Quay Container Registry organizations
+`quay_organization_prune` | Manage auto-pruning policies for organizations and user namespaces
 `quay_proxy_cache` |        Manage Quay Container Registry proxy cache configurations
 `quay_quota` |              Manage Quay Container Registry organizations quota
 `quay_repository` |         Manage Quay Container Registry repositories
 `quay_repository_mirror` |  Manage Quay Container Registry repository mirror configurations
+`quay_repository_prune` |   Manage auto-pruning policies for repositories
 `quay_robot` |              Manage Quay Container Registry robot accounts
 `quay_tag` |                Manage Quay Container Registry image tags
 `quay_tag_info` |           Gather information about tags in a Quay Container Registry repository

diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml
@@ -254,3 +254,22 @@ releases:
     fragments:
     - PR5-v2.2.0-summary.yml
     release_date: '2024-08-05'
+  2.4.0:
+    changes:
+      deprecated_features:
+      - The ``auto_prune_method`` and ``auto_prune_value`` parameters of the ``infra.quay_configuration.quay_organization``
+        and ``infra.quay_configuration.quay_repository`` modules are deprecated in
+        favor of the new``infra.quay_configuration.quay_organization_prune`` and ``infra.quay_configuration.quay_repository_prune``
+        modules.
+      release_summary: New ``infra.quay_configuration.quay_organization_prune`` and
+        ``infra.quay_configuration.quay_repository_prune`` modules.
+    fragments:
+    - PR16-v2.4.0-summary.yml
+    modules:
+    - description: Manage auto-pruning policies for organizations and user namespaces
+      name: quay_organization_prune
+      namespace: ''
+    - description: Manage auto-pruning policies for repositories
+      name: quay_repository_prune
+      namespace: ''
+    release_date: '2024-11-23'
diff --git a/galaxy.yml b/galaxy.yml
@@ -1,7 +1,7 @@
 ---
 namespace: infra
 name: quay_configuration
-version: 2.2.0
+version: 2.4.0
 readme: README.md
 authors:
   - Hervé Quatremain <[email protected]>

diff --git a/meta/runtime.yml b/meta/runtime.yml
@@ -11,10 +11,12 @@ action_groups:
     - quay_manifest_label
     - quay_message
     - quay_notification
+    - quay_organization_prune
     - quay_organization
     - quay_proxy_cache
     - quay_quota
     - quay_repository_mirror
+    - quay_repository_prune
     - quay_repository
     - quay_robot
     - quay_tag_info

diff --git a/plugins/doc_fragments/autoprune.py b/plugins/doc_fragments/autoprune.py
@@ -12,32 +12,41 @@ class ModuleDocFragment(object):
     # Ansible Galaxy documentation fragment
     DOCUMENTATION = r"""
 options:
-  auto_prune_method:
+  method:
     description:
       - Method to use for the auto-pruning tags policy.
-      - If V(none), then the module ensures that no policy is in place. The
-        tags are not pruned.
       - If V(tags), then the policy keeps only the number of tags that you
-        specify in O(auto_prune_value).
+        specify in O(value).
       - If V(date), then the policy deletes the tags older than the time period
-        that you specify in O(auto_prune_value).
-      - O(auto_prune_value) is required when O(auto_prune_method) is V(tags) or
-        V(date).
+        that you specify in O(value).
+    required: true
     type: str
-    choices: [none, tags, date]
-  auto_prune_value:
+    choices: [tags, date]
+  value:
     description:
-      - Number of tags to keep when O(auto_prune_method) is V(tags).
+      - Number of tags to keep when O(method) is V(tags).
         The value must be 1 or more.
-      - Period of time when O(auto_prune_method) is V(date). The value must be 1
-        or more, and must be followed by a suffix; s (for second), m (for
-        minute), h (for hour), d (for day), or w (for week).
-      - O(auto_prune_method) is required when O(auto_prune_value) is set.
+      - Period of time when O(method) is V(date). The value must be 1 or more,
+        and must be followed by a suffix; s (for second), m (for minute), h
+        (for hour), d (for day), or w (for week).
+    required: true
     type: str
+  tag_pattern:
+    description:
+      - Regular expression to select the tags to process.
+      - If you do not set the parameter, then Quay processes all the tags.
+    type: str
+  tag_pattern_matches:
+    description:
+      - If V(true), then Quay processes the tags matching the O(tag_pattern)
+        parameter.
+      - If V(false), then Quay excludes the tags matching the O(tag_pattern)
+        parameter.
+      - V(true) by default.
+    type: bool
+    default: true
 notes:
-  - Your Quay administrator must enable the auto-prune capability of your Quay
-    installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)) to use the
-    O(auto_prune_method) and O(auto_prune_value) parameters.
-  - Using O(auto_prune_method) and O(auto_prune_value) requires Quay version
-    3.11 or later.
+  - Your Quay administrator must enable the auto-pruning capability of your
+    Quay installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)).
+  - Auto-pruning requires Quay version 3.13 or later.
 """
diff --git a/plugins/doc_fragments/autoprune_deprecated.py b/plugins/doc_fragments/autoprune_deprecated.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2024 Hervé Quatremain <[email protected]>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+    # Ansible Galaxy documentation fragment
+    DOCUMENTATION = r"""
+options:
+  auto_prune_method:
+    description:
+      - The O(auto_prune_method) parameter is deprecated and will be removed in
+        future versions of the collection.
+        Use the M(infra.quay_configuration.quay_organization_prune) and the
+        M(infra.quay_configuration.quay_repository_prune) modules instead.
+      - Method to use for the auto-pruning tags policy.
+      - If V(none), then the module ensures that no policy is in place. The
+        tags are not pruned.
+        If several policies are available, then the module removes them all.
+      - If V(tags), then the policy keeps only the number of tags that you
+        specify in O(auto_prune_value).
+      - If V(date), then the policy deletes the tags older than the time period
+        that you specify in O(auto_prune_value).
+      - O(auto_prune_value) is required when O(auto_prune_method) is V(tags) or
+        V(date).
+    type: str
+    choices: [none, tags, date]
+  auto_prune_value:
+    description:
+      - The O(auto_prune_value) parameter is deprecated and will be removed in
+        future versions of the collection.
+        Use the M(infra.quay_configuration.quay_organization_prune) and the
+        M(infra.quay_configuration.quay_repository_prune) modules instead.
+      - Number of tags to keep when O(auto_prune_method) is V(tags).
+        The value must be 1 or more.
+      - Period of time when O(auto_prune_method) is V(date). The value must be 1
+        or more, and must be followed by a suffix; s (for second), m (for
+        minute), h (for hour), d (for day), or w (for week).
+      - O(auto_prune_method) is required when O(auto_prune_value) is set.
+    type: str
+notes:
+  - The O(auto_prune_method) and O(auto_prune_value) parameters are deprecated
+    and will be removed in future versions of the collection.
+    Use the M(infra.quay_configuration.quay_organization_prune) and the
+    M(infra.quay_configuration.quay_repository_prune) modules instead.
+  - Your Quay administrator must enable the auto-prune capability of your Quay
+    installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)) to use the
+    O(auto_prune_method) and O(auto_prune_value) parameters.
+  - Using O(auto_prune_method) and O(auto_prune_value) requires Quay version
+    3.11 or later.
+"""
diff --git a/plugins/module_utils/api_module.py b/plugins/module_utils/api_module.py
@@ -1354,6 +1354,71 @@ def get_tags(self, namespace, repository, tag=None, digest=None, only_active_tag
             break
         return tag_list
 
+    def process_prune_parameters(
+        self, method, value, tag_pattern=None, tag_pattern_matches=True
+    ):
+        """Return the prune parameters in a dictionary ready for the API.
+
+        :param method: The prune method: "tags", or "date".
+        :type method: str
+        :param value: The pruning criteria, which depends on the method. It can
+                      be a number of tags, or a period of time.
+        :type value: str
+        :param tag_pattern: A regular expression that is used to select the tags
+                            to purge.
+        :type tag_pattern: str
+        :param tag_pattern_matches: If ``True``, then the tags matching
+                                    :py:attribute:``tag_pattern`` are processed.
+                                    If ``False``, then the tags matching
+                                    :py:attribute:``tag_pattern`` are excluded.
+        :type tag_pattern_matches: bool
+
+        :return: The prune parameters ready to be used for a call to the API.
+                 For example::
+
+                    {
+                        "method": "creation_date",
+                        "value": "7d",
+                        "tagPattern": "dev.*",
+                        "tagPatternMatches": True
+                    }
+        """
+        if method == "tags":
+            try:
+                auto_prune_value = int(value)
+            except ValueError:
+                self.fail_json(
+                    msg=(
+                        "Wrong format for the `value' parameter:"
+                        " {auto_prune_value} is not a positive integer."
+                    ).format(auto_prune_value=value)
+                )
+            if auto_prune_value <= 0:
+                self.fail_json(
+                    msg=(
+                        "Wrong format for the `value' parameter:"
+                        " {auto_prune_value} is not a positive integer."
+                    ).format(auto_prune_value=value)
+                )
+            data = {"method": "number_of_tags", "value": auto_prune_value}
+        else:  # method == "date":
+            auto_prune_value = "".join(value.split())
+            if not re.match(r"[1-9]\d*[smhdw]$", auto_prune_value):
+                self.fail_json(
+                    msg=(
+                        "Wrong format for the `value' parameter:"
+                        " {auto_prune_value} is not a positive integer followed by"
+                        " the s, m, h, d, or w suffix."
+                    ).format(auto_prune_value=value)
+                )
+            data = {"method": "creation_date", "value": auto_prune_value}
+        if tag_pattern:
+            data["tagPattern"] = tag_pattern
+            data["tagPatternMatches"] = (
+                tag_pattern_matches if tag_pattern_matches is not None else True
+            )
+        return data
+
 
 class APIModuleNoAuth(APIModule):
     AUTH_ARGSPEC = dict(

diff --git a/plugins/modules/quay_default_perm.py b/plugins/modules/quay_default_perm.py
@@ -35,8 +35,8 @@
 options:
   organization:
     description:
-      - Name of the organization for the default permission.
-        That organization must exist.
+      - Name of the organization for the default permission. This organization
+        must exist.
     required: true
     type: str
   name:

diff --git a/plugins/modules/quay_organization.py b/plugins/modules/quay_organization.py
@@ -72,11 +72,6 @@
     default: present
     choices: [absent, present]
 notes:
-  - Your Quay administrator must enable the auto-prune capability of your Quay
-    installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)) to use the
-    O(auto_prune_method) and O(auto_prune_value) parameters.
-  - Using O(auto_prune_method) and O(auto_prune_value) requires Quay version
-    3.11 or later.
   - The token that you provide in O(quay_token) must have the "Administer
     Organization" and "Administer User" permissions.
   - To rename organizations, the token must also have the "Super User Access"
@@ -93,7 +88,7 @@
   - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
-  - infra.quay_configuration.autoprune
+  - infra.quay_configuration.autoprune_deprecated
 """
 
 EXAMPLES = r"""
@@ -102,8 +97,6 @@
     name: production
     email: [email protected]
     time_machine_expiration: "7d"
-    auto_prune_method: tags
-    auto_prune_value: 20
     state: present
     quay_host: https://quay.example.com
     quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
@@ -144,8 +137,14 @@ def main():
         new_name=dict(),
         email=dict(),
         time_machine_expiration=dict(choices=list(tm_allowed_values.keys())),
-        auto_prune_method=dict(choices=["none", "tags", "date"]),
-        auto_prune_value=dict(),
+        auto_prune_method=dict(
+            choices=["none", "tags", "date"],
+            removed_at_date="2025-12-01",
+            removed_from_collection="infra.quay_configuration",
+        ),
+        auto_prune_value=dict(
+            removed_at_date="2025-12-01", removed_from_collection="infra.quay_configuration"
+        ),
         state=dict(choices=["present", "absent"], default="present"),
     )
 
@@ -330,15 +329,14 @@ def main():
         except (TypeError, IndexError):
             policies = []
 
-        # Removing the auto-prune policies (the UI only manages one policy, but
-        # the backend seems to allow several policies)
+        # Removing all the auto-pruning policies
         if auto_prune_method == "none":
             deleted = False
             for policy in policies:
                 uuid = policy.get("uuid")
                 if module.delete(
                     uuid,
-                    "organization auto-prune policy",
+                    "organization auto-pruning policy",
                     name,
                     "organization/{orgname}/autoprunepolicy/{uuid}",
                     auto_exit=False,
@@ -366,7 +364,7 @@ def main():
                 # then create the policy
                 if len(policies) == 0 or policies[0].get("uuid") is None:
                     module.create(
-                        "organization auto-prune policy",
+                        "organization auto-pruning policy",
                         name,
                         "organization/{orgname}/autoprunepolicy/",
                         new_policy,
@@ -379,7 +377,7 @@ def main():
                     uuid = policies[0]["uuid"]
                     new_policy["uuid"] = uuid
                     module.unconditional_update(
-                        "organization auto-prune policy",
+                        "organization auto-pruning policy",
                         name,
                         "organization/{orgname}/autoprunepolicy/{uuid}",
                         new_policy,