Merge pull request #2 from herve4m/herve4m/image_expiry_notification

New repo_image_expiry notification event (Quay 3.12)

CHANGELOG.rst

@@ -4,6 +4,19 @@ Quay Container Registry Collection Release Notes
 
 .. contents:: Topics
 
+v2.1.0
+======
+
+Release Summary
+---------------
+
+Adding the ``repo_image_expiry`` event to the ``herve4m.quay.quay_notification`` module.
+
+Minor Changes
+-------------
+
+- herve4m.quay.quay_notification - New ``repo_image_expiry`` event and new ``image_expiry_days`` parameter (Quay 3.12)
+
 v2.0.0
 ======
 

README.md

@@ -9,7 +9,7 @@ The collection provides modules for managing your Quay Container Registry deploy
 
 ## Included Content
 
-The modules have been tested against versions 3.9, 3.10, and 3.11 of Quay Container Registry.
+The modules have been tested against versions 3.10, 3.11, and 3.12 of Quay Container Registry.
 
 ### Modules
 Name | Description

changelogs/changelog.yaml

@@ -234,3 +234,13 @@ releases:
     fragments:
     - PR1-v2.0.0-summary.yaml
     release_date: '2024-07-26'
+  2.1.0:
+    changes:
+      minor_changes:
+      - herve4m.quay.quay_notification - New ``repo_image_expiry`` event and new ``image_expiry_days``
+        parameter (Quay 3.12)
+      release_summary: Adding the ``repo_image_expiry`` event to the ``herve4m.quay.quay_notification``
+        module.
+    fragments:
+    - PR2-v2.1.0-summary.yml
+    release_date: '2024-07-29'

docs/index.rst

@@ -9,7 +9,7 @@
 Infra.Quay_Configuration
 ========================
 
-Collection version 2.0.0
+Collection version 2.1.0
 
 .. contents::
    :local:

docs/quay_api_token_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_api_token module -- Create OAuth access tokens for
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.
@@ -206,6 +206,7 @@ Notes
 .. note::
    - Supports \ :literal:`check\_mode`\ .
    - The generated OAuth access token acts on behalf of the user account you use with the module (in \ :emphasis:`quay\_username`\ ).
+   - The user must have admin rights to the application's organization, by being the creator of this organization, or by belonging to a team with admin rights.
    - The module is not idempotent. Every time you run it, an additional OAuth access token is produced. The other OAuth access tokens stay valid.
    - You cannot delete OAuth access tokens.
 
@@ -224,8 +225,9 @@ Examples
       infra.quay_configuration.quay_api_token:
         quay_username: lvasquez
         quay_password: vs9mrD55NP
-        # The OAuth application must exist. See the following example that shows
-        # how to create an organization and an application.
+        # The OAuth application must exist, and the user must have admin rights
+        # to the organization that hosts the application. See the following example
+        # that shows how to create an organization, a team, and an application.
         client_id: PZ6F80R1LCVPGYNZGSZQ
         rights:
           - org:admin
@@ -238,9 +240,11 @@ Examples
         msg: "The OAuth access token is: {{ token_details['access_token'] }}"
 
     # The following example creates an organization, an OAuth application, a user
-    # account, and then generates an OAuth access token for that user account.
+    # account, and a team, and then generates an OAuth access token for this user
+    # account.
+    # The team grants organization admin rights to the user.
     # The OAuth access token of an existing super user is required to create the
-    # organization, the application, and the user account.
+    # organization, the application, the user account, and the team.
     - name: Ensure the organization exists
       infra.quay_configuration.quay_organization:
         name: production
@@ -249,7 +253,7 @@ Examples
         quay_host: https://quay.example.com
         quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
 
-    - name: Ensure the application extapp exists
+    - name: Ensure the extapp application exists
       infra.quay_configuration.quay_application:
         organization: production
         name: extapp
@@ -267,6 +271,17 @@ Examples
         quay_host: https://quay.example.com
         quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
 
+    - name: Ensure the operators team exists in the production organization
+      infra.quay_configuration.quay_team:
+        name: operators
+        organization: production
+        role: admin
+        members:
+          - jziglar
+        state: present
+        quay_host: https://quay.example.com
+        quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
+
     - name: Generate an OAuth access token for the user
       infra.quay_configuration.quay_api_token:
         quay_username: jziglar

docs/quay_application_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_application module -- Manage Quay Container Regist
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_default_perm_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_default_perm module -- Manage Quay Container Regis
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_docker_config_filter.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_docker_config filter -- Build a Docker configurati
 .. Collection note
 
 .. note::
-    This filter plugin is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This filter plugin is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_docker_token_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_docker_token module -- Manage tokens for accessing
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_first_user_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_first_user module -- Create the first user account
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_layer_info_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_layer_info module -- Gather information about imag
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_manifest_label_info_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_manifest_label_info module -- Gather information a
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_manifest_label_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_manifest_label module -- Manage Quay Container Reg
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_message_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_message module -- Manage Quay Container Registry g
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.

docs/quay_notification_module.rst

@@ -23,7 +23,7 @@ infra.quay_configuration.quay_notification module -- Manage Quay Container Regis
 .. Collection note
 
 .. note::
-    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This module is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.
@@ -230,11 +230,27 @@ Parameters
         <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;repo_mirror_sync_started&#34;</code></p></li>
         <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;repo_mirror_sync_success&#34;</code></p></li>
         <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;repo_mirror_sync_failed&#34;</code></p></li>
+        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;repo_image_expiry&#34;</code></p></li>
       </ul>
 
     </div></td>
   </tr>
   <tr class="row-even">
+    <td><div class="ansible-option-cell">
+      <div class="ansibleOptionAnchor" id="parameter-image_expiry_days"></div>
+      <p class="ansible-option-title"><strong>image_expiry_days</strong></p>
+      <a class="ansibleOptionLink" href="#parameter-image_expiry_days" title="Permalink to this option"></a>
+      <p class="ansible-option-type-line">
+        <span class="ansible-option-type">integer</span>
+      </p>
+    </div></td>
+    <td><div class="ansible-option-cell">
+      <p>Only used when <em>event</em> is <code class='docutils literal notranslate'>repo_image_expiry</code>.</p>
+      <p>The notification is triggered when the image expires in the specified number of days.</p>
+      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">7</code></p>
+    </div></td>
+  </tr>
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-method"></div>
       <p class="ansible-option-title"><strong>method</strong></p>
@@ -258,7 +274,7 @@ Parameters
 
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-quay_host"></div>
       <p class="ansible-option-title"><strong>quay_host</strong></p>
@@ -274,7 +290,7 @@ Parameters
       <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;http://127.0.0.1&#34;</code></p>
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-quay_password"></div>
       <p class="ansible-option-title"><strong>quay_password</strong></p>
@@ -290,7 +306,7 @@ Parameters
       <p>Mutually exclusive with <em>quay_token</em>.</p>
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-quay_token"></div>
       <p class="ansible-option-title"><strong>quay_token</strong></p>
@@ -305,7 +321,7 @@ Parameters
       <p>Mutually exclusive with <em>quay_username</em> and <em>quay_password</em>.</p>
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-quay_username"></div>
       <p class="ansible-option-title"><strong>quay_username</strong></p>
@@ -321,7 +337,7 @@ Parameters
       <p>Mutually exclusive with <em>quay_token</em>.</p>
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-regexp"></div>
       <div class="ansibleOptionAnchor" id="parameter-regex"></div>
@@ -341,7 +357,7 @@ Parameters
       <p>Mutually exclusive with <em>search_string</em>.</p>
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-repository"></div>
       <p class="ansible-option-title"><strong>repository</strong></p>
@@ -356,7 +372,7 @@ Parameters
       <p>If you omit the namespace part in the name, then the module looks for the repository in your personal namespace.</p>
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-reset_failcount"></div>
       <p class="ansible-option-title"><strong>reset_failcount</strong></p>
@@ -375,7 +391,7 @@ Parameters
 
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-search_string"></div>
       <p class="ansible-option-title"><strong>search_string</strong></p>
@@ -391,7 +407,7 @@ Parameters
       <p>Mutually exclusive with <em>regexp</em>.</p>
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-state"></div>
       <p class="ansible-option-title"><strong>state</strong></p>
@@ -413,7 +429,7 @@ Parameters
 
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-test"></div>
       <p class="ansible-option-title"><strong>test</strong></p>
@@ -432,7 +448,7 @@ Parameters
 
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-title"></div>
       <p class="ansible-option-title"><strong>title</strong></p>
@@ -445,7 +461,7 @@ Parameters
       <p>Notification title.</p>
     </div></td>
   </tr>
-  <tr class="row-even">
+  <tr class="row-odd">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-validate_certs"></div>
       <div class="ansibleOptionAnchor" id="parameter-verify_ssl"></div>
@@ -468,7 +484,7 @@ Parameters
 
     </div></td>
   </tr>
-  <tr class="row-odd">
+  <tr class="row-even">
     <td><div class="ansible-option-cell">
       <div class="ansibleOptionAnchor" id="parameter-vulnerability_level"></div>
       <p class="ansible-option-title"><strong>vulnerability_level</strong></p>
@@ -507,6 +523,8 @@ Notes
 
 .. note::
    - Supports \ :literal:`check\_mode`\ .
+   - Your Quay administrator must enable the image garbage collection capability of your Quay installation (\ :literal:`FEATURE\_GARBAGE\_COLLECTION`\  in \ :literal:`config.yaml`\ ) to use the \ :literal:`repo\_image\_expiry`\  event.
+   - Using the \ :literal:`repo\_image\_expiry`\  event and the \ :emphasis:`image\_expiry\_days`\  parameter requires Quay version 3.12 or later.
    - The user account associated with the token that you provide in \ :emphasis:`quay\_token`\  must have administrator access to the repository.
 
 .. Seealso
@@ -549,6 +567,22 @@ Examples
         quay_host: https://quay.example.com
         quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
 
+    # You must enable the image garbage collection capability of your Quay
+    # installation (3.12 or later) to use the repo_image_expiry event.
+    - name: Ensure notification exists for when an image is going to expire
+      infra.quay_configuration.quay_notification:
+        repository: production/smallimage
+        title: Webhook notification 10 days before an image expires
+        event: repo_image_expiry
+        image_expiry_days: 10
+        method: webhook
+        config:
+          url: https://webhook.example.com/webhook/12345
+          template: "{{ lookup('file', 'post.json') | string }}"
+        state: present
+        quay_host: https://quay.example.com
+        quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
+
     - name: Ensure notification of type Slack exists
       infra.quay_configuration.quay_notification:
         repository: production/smallimage

docs/quay_org_role.rst

@@ -22,7 +22,7 @@ infra.quay_configuration.quay_org role -- Create and configure a Quay Container
 .. Collection note
 
 .. note::
-    This role is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.0.0).
+    This role is part of the `infra.quay_configuration collection <https://galaxy.ansible.com/ui/repo/published/infra/quay_configuration/>`_ (version 2.1.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.