x509_crl: prepare releasing the mode option for AnsibleModule's use (#596)

* Prepare releasing the mode option for AnsibleModule's use.

* Update docs.

changelogs/fragments/596-x509_crl-mode.yml

@@ -0,0 +1,6 @@
+bugfixes:
+  - "x509_crl - remove problem with ansible-core 2.16 due to ``AnsibleModule`` is now validating the ``mode`` parameter's values (https://github.com/ansible-collections/community.crypto/issues/596)."
+minor_changes:
+  - "x509_crl - the ``crl_mode`` option has been added to replace the existing ``mode`` option (https://github.com/ansible-collections/community.crypto/issues/596)."
+deprecated_features:
+  - "x509_crl - the ``mode`` option is deprecated; use ``crl_mode`` instead. The ``mode`` option will change its meaning in community.crypto 3.0.0, and will refer to the CRL file's mode instead (https://github.com/ansible-collections/community.crypto/issues/596)."

plugins/modules/x509_crl.py

@@ -42,7 +42,7 @@ options:
         default: present
         choices: [ absent, present ]
 
-    mode:
+    crl_mode:
         description:
             - Defines how to process entries of existing CRLs.
             - If set to C(generate), makes sure that the CRL has the exact set of revoked certificates
@@ -51,8 +51,20 @@ options:
               I(revoked_certificates), but can also contain other revoked certificates. If the CRL file
               already exists, all entries from the existing CRL will also be included in the new CRL.
               When using C(update), you might be interested in setting I(ignore_timestamps) to C(true).
+            - The default value is C(generate).
+            - This parameter was called I(mode) before community.crypto 2.13.0. It has been renamed to avoid
+              a collision with the common I(mode) parameter for setting the CRL file's access mode.
         type: str
-        default: generate
+        # default: generate
+        choices: [ generate, update ]
+        version_added: 2.13.0
+    mode:
+        description:
+            - This parameter has been renamed to I(crl_mode). The old name I(mode) is now deprecated and will
+              be removed in community.crypto 3.0.0. Replace usage of this parameter with I(crl_mode).
+            - Note that from community.crypto 3.0.0 on, I(mode) will be used for the CRL file's mode.
+        type: str
+        # default: generate
         choices: [ generate, update ]
 
     force:
@@ -479,7 +491,7 @@ class CRL(OpenSSLObject):
 
         self.format = module.params['format']
 
-        self.update = module.params['mode'] == 'update'
+        self.update = module.params['crl_mode'] == 'update'
         self.ignore_timestamps = module.params['ignore_timestamps']
         self.return_content = module.params['return_content']
         self.name_encoding = module.params['name_encoding']
@@ -827,7 +839,18 @@ def main():
     module = AnsibleModule(
         argument_spec=dict(
             state=dict(type='str', default='present', choices=['present', 'absent']),
-            mode=dict(type='str', default='generate', choices=['generate', 'update']),
+            crl_mode=dict(
+                type='str',
+                # default='generate',
+                choices=['generate', 'update'],
+            ),
+            mode=dict(
+                type='str',
+                # default='generate',
+                choices=['generate', 'update'],
+                removed_in_version='3.0.0',
+                removed_from_collection='community.crypto',
+            ),
             force=dict(type='bool', default=False),
             backup=dict(type='bool', default=False),
             path=dict(type='path', required=True),
@@ -882,6 +905,14 @@ def main():
         add_file_common_args=True,
     )
 
+    if module.params['mode']:
+        if module.params['crl_mode']:
+            module.fail_json('You cannot use both `mode` and `crl_mode`. Use `crl_mode`.')
+        module.params['crl_mode'] = module.params['mode']
+    # TODO: in 3.0.0, once the option `mode` has been removed, remove this:
+    module.params.pop('mode', None)
+    # From then on, `mode` will be the file mode of the CRL file
+
     if not CRYPTOGRAPHY_FOUND:
         module.fail_json(msg=missing_required_lib('cryptography >= {0}'.format(MINIMAL_CRYPTOGRAPHY_VERSION)),
                          exception=CRYPTOGRAPHY_IMP_ERR)

tests/integration/targets/filter_x509_crl_info/tasks/impl.yml

@@ -130,7 +130,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: false
-    mode: update
+    crl_mode: update
     return_content: true
   register: crl_2_change
 
@@ -156,7 +156,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
     return_content: true
   register: crl_2_change_order
 

tests/integration/targets/x509_crl/tasks/impl.yml

@@ -360,7 +360,7 @@
     revoked_certificates:
       - serial_number: 1235
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
   check_mode: true
   register: crl_2_idem_update_change_check
 
@@ -378,7 +378,7 @@
     revoked_certificates:
       - serial_number: 1235
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
   register: crl_2_idem_update_change
 
 - name: Create CRL 2 (idempotent update, check mode)
@@ -398,7 +398,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
   check_mode: true
   register: crl_2_idem_update_check
 
@@ -419,7 +419,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
   register: crl_2_idem_update
 
 - name: Create CRL 2 (changed timestamps, check mode)
@@ -439,7 +439,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: false
-    mode: update
+    crl_mode: update
   check_mode: true
   register: crl_2_change_check
 
@@ -460,7 +460,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: false
-    mode: update
+    crl_mode: update
     return_content: true
   register: crl_2_change
 
@@ -493,7 +493,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
     return_content: true
   register: crl_2_change_order_ignore
 
@@ -514,7 +514,7 @@
         reason_critical: true
         invalidity_date: 20191012000000Z
     ignore_timestamps: true
-    mode: update
+    crl_mode: update
     return_content: true
   register: crl_2_change_order