Add 'idempotent' attribute (#833)

* Add 'idempotent' attribute.

* Mention check mode in attribute description.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

---------

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

plugins/doc_fragments/attributes.py

@@ -18,6 +18,20 @@ attributes:
     description: Can run in C(check_mode) and return changed status prediction without modifying target.
   diff_mode:
     description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  idempotent:
+    description:
+      - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+      - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+"""
+
+    # Should be used together with the standard fragment
+    IDEMPOTENT_NOT_MODIFY_STATE = r"""
+options: {}
+attributes:
+  idempotent:
+    support: full
+    details:
+      - This action does not modify state.
 """
 
     # Should be used together with the standard fragment

plugins/doc_fragments/module_certificate.py

@@ -19,6 +19,11 @@ description:
 attributes:
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If relative timestamps are used and O(ignore_timestamps=false), the module is not idempotent.
+      - The option O(force=true) generally disables idempotency.
 requirements:
   - cryptography >= 1.6 (if using V(selfsigned) or V(ownca) provider)
 options:

plugins/doc_fragments/module_csr.py

@@ -18,6 +18,8 @@ description:
 attributes:
   diff_mode:
     support: full
+  idempotent:
+    support: full
 requirements:
   - cryptography >= 1.3
 options:

plugins/doc_fragments/module_privatekey.py

@@ -20,6 +20,10 @@ description:
 attributes:
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The option O(regenerate=always) generally disables idempotency.
 requirements:
   - cryptography >= 1.2.3 (older versions might work as well)
 options:

plugins/doc_fragments/module_privatekey_convert.py

@@ -17,6 +17,8 @@ requirements:
 attributes:
   diff_mode:
     support: none
+  idempotent:
+    support: full
 options:
   src_path:
     description:

plugins/modules/acme_account.py

@@ -43,6 +43,10 @@ attributes:
     support: full
   diff_mode:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If O(state=changed_key) is used, the module is not idempotent.
 options:
   state:
     description:

plugins/modules/acme_account_info.py

@@ -26,6 +26,7 @@ extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.actiongroup_acme
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   retrieve_orders:
     description:

plugins/modules/acme_ari_info.py

@@ -24,6 +24,7 @@ extends_documentation_fragment:
   - community.crypto.acme.no_account
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   certificate_path:
     description:

plugins/modules/acme_certificate.py

@@ -81,6 +81,12 @@ attributes:
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - If O(force=true), the module is not idempotent.
+        If O(force=false), it depends on the certificate's validity period and the value of O(remaining_days).
+      - The second phase invocation of the module is always idempotent, assuming no error occurs.
 options:
   account_email:
     description:

plugins/modules/acme_certificate_deactivate_authz.py

@@ -33,6 +33,8 @@ attributes:
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: full
 options:
   order_uri:
     description:

plugins/modules/acme_certificate_renewal_info.py

@@ -23,6 +23,7 @@ extends_documentation_fragment:
   - community.crypto.acme.no_account
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   certificate_path:
     description:

plugins/modules/acme_certificate_revoke.py

@@ -41,6 +41,8 @@ attributes:
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: full
 options:
   certificate:
     description:

plugins/modules/acme_challenge_cert_helper.py

@@ -37,6 +37,11 @@ attributes:
     support: N/A
     details:
       - This action does not modify state.
+  idempotent:
+    support: none
+    details:
+      - The certificates returned are never the same, since the Not Before and Not After timestamps
+        depend on the invocation's timestamp.
 options:
   challenge:
     description:

plugins/modules/acme_inspect.py

@@ -44,6 +44,8 @@ attributes:
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: none
 options:
   url:
     description:

plugins/modules/certificate_complete_chain.py

@@ -24,6 +24,7 @@ requirements:
   - "cryptography >= 1.5"
 extends_documentation_fragment:
   - community.crypto.attributes
+  - community.crypto.attributes.idempotent_not_modify_state
 attributes:
   check_mode:
     support: full

plugins/modules/crypto_info.py

@@ -21,6 +21,7 @@ description:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options: {}
 """
 

plugins/modules/ecs_certificate.py

@@ -37,6 +37,13 @@ attributes:
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true).
+      - Under which conditions the module is idempotent still needs to be determined.
+        If you are using this module and have more information, please contribute to
+        the documentation!
 options:
   backup:
     description:

plugins/modules/ecs_domain.py

@@ -44,6 +44,12 @@ attributes:
     support: none
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - Under which conditions the module is idempotent still needs to be determined.
+        If you are using this module and have more information, please contribute to
+        the documentation!
 options:
   client_id:
     description:

plugins/modules/get_certificate.py

@@ -20,6 +20,7 @@ description:
     newer.
 extends_documentation_fragment:
   - community.crypto.attributes
+  - community.crypto.attributes.idempotent_not_modify_state
 attributes:
   check_mode:
     support: none

plugins/modules/luks_device.py

@@ -23,6 +23,8 @@ attributes:
     support: full
   diff_mode:
     support: none
+  idempotent:
+    support: full
 
 options:
   device:

plugins/modules/openssh_cert.py

@@ -28,6 +28,11 @@ attributes:
     support: full
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true) or O(regenerate=always).
+      - If relative timestamps are used and O(ignore_timestamps=false) (default), the module is not idempotent.
 options:
   state:
     description:

plugins/modules/openssh_keypair.py

@@ -30,6 +30,10 @@ attributes:
     support: full
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true) or O(regenerate=always).
 options:
   state:
     description:

plugins/modules/openssl_csr_info.py

@@ -26,6 +26,7 @@ extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
   - community.crypto.name_encoding
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   path:
     description:

plugins/modules/openssl_dhparam.py

@@ -35,6 +35,10 @@ attributes:
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true).
 options:
   state:
     description:

plugins/modules/openssl_pkcs12.py

@@ -32,6 +32,10 @@ attributes:
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true).
 options:
   action:
     description:

plugins/modules/openssl_privatekey_info.py

@@ -27,6 +27,7 @@ author:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   path:
     description:

plugins/modules/openssl_publickey.py

@@ -34,6 +34,10 @@ attributes:
     support: full
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true).
 options:
   state:
     description:

plugins/modules/openssl_publickey_info.py

@@ -23,6 +23,7 @@ author:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   path:
     description:

plugins/modules/openssl_signature.py

@@ -30,6 +30,11 @@ attributes:
       - This action does not modify state.
   diff_mode:
     support: none
+  idempotent:
+    support: partial
+    details:
+      - Signature algorithms are generally not deterministic. Thus the generated signature
+        can change from one invocation to the next.
 options:
   privatekey_path:
     description:

plugins/modules/openssl_signature_info.py

@@ -24,6 +24,7 @@ author:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
 options:
   path:
     description:

plugins/modules/x509_certificate_convert.py

@@ -28,6 +28,8 @@ attributes:
     support: none
   safe_file_operations:
     support: full
+  idempotent:
+    support: full
 options:
   src_path:
     description:

plugins/modules/x509_certificate_info.py

@@ -31,6 +31,7 @@ author:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
   - community.crypto.name_encoding
 options:
   path:

plugins/modules/x509_crl.py

@@ -33,6 +33,11 @@ attributes:
     support: full
   safe_file_operations:
     support: full
+  idempotent:
+    support: partial
+    details:
+      - The module is not idempotent if O(force=true).
+      - If relative timestamps and O(ignore_timestamps=false) (default), the module is not idempotent.
 options:
   state:
     description:

plugins/modules/x509_crl_info.py

@@ -22,6 +22,7 @@ author:
 extends_documentation_fragment:
   - community.crypto.attributes
   - community.crypto.attributes.info_module
+  - community.crypto.attributes.idempotent_not_modify_state
   - community.crypto.name_encoding
 options:
   path: