ansible-collections · briantist · Nov 5, 2022 · Nov 3, 2022 · Nov 3, 2022 · Nov 4, 2022
diff --git a/changelogs/fragments/197-module-attributes.yml b/changelogs/fragments/197-module-attributes.yml
@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - modules - all modules now document their action group and support for check mode in their attributes documentation (https://github.com/ansible-collections/community.hashi_vault/issues/197).
diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2022, Brian Scholer (@briantist)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = r'''
+options: {}
+'''
+
+    ACTION_GROUP = r'''
+options: {}
+attributes:
+  action_group:
+    description: Use C(group/community.hashi_vault.vault) in C(module_defaults) to set defaults for this module.
+    support: full
+    membership:
+      - community.hashi_vault.vault
+'''
+
+    CHECK_MODE_READ_ONLY = r'''
+options: {}
+attributes:
+  check_mode:
+    support: full
+    description: This module is "read only" and operates the same regardless of check mode.
+'''
diff --git a/plugins/modules/vault_kv1_get.py b/plugins/modules/vault_kv1_get.py
@@ -26,6 +26,8 @@
     description: Documentation for the Vault KV secrets engine, version 1.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v1
 extends_documentation_fragment:
+  - community.hashi_vault.attributes.action_group
+  - community.hashi_vault.attributes.check_mode_read_only
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount

diff --git a/plugins/modules/vault_kv2_delete.py b/plugins/modules/vault_kv2_delete.py
@@ -21,14 +21,19 @@
 notes:
   - This module always reports C(changed) status because it cannot guarantee idempotence.
   - Use C(changed_when) to control that in cases where the operation is known to not change state.
-  - In check mode, the module returns C(changed) status without contacting Vault.
-    Consider using M(community.hashi_vault.vault_kv2_get) to verify the existence of the secret first.
+attributes:
+  check_mode:
+    support: partial
+    description:
+      - In check mode, the module returns C(changed) status without contacting Vault.
+        Consider using M(community.hashi_vault.vault_kv2_get) to verify the existence of the secret first.
 seealso:
   - module: community.hashi_vault.vault_kv2_get
   - name: KV2 Secrets Engine
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
+  - community.hashi_vault.attributes.action_group
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount

diff --git a/plugins/modules/vault_kv2_get.py b/plugins/modules/vault_kv2_get.py
@@ -26,6 +26,8 @@
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
+  - community.hashi_vault.attributes.action_group
+  - community.hashi_vault.attributes.check_mode_read_only
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount

diff --git a/plugins/modules/vault_login.py b/plugins/modules/vault_login.py
@@ -24,6 +24,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   notes:
@@ -36,9 +37,13 @@
     - "The C(token) auth method will only return full information if I(token_validate=True).
       If the token does not have the C(lookup-self) capability, this will fail. If I(token_validate=False), only the token value itself
       will be returned in the structure."
-    - "In check mode, this module will not perform a login, and will instead return a basic structure with an empty token.
-      However this may not be useful if the token is required for follow on tasks.
-      It may be better to use this module with C(check_mode=no) in order to have a valid token that can be used."
+  attributes:
+    check_mode:
+      support: partial
+      description:
+        - "In check mode, this module will not perform a login, and will instead return a basic structure with an empty token.
+          However this may not be useful if the token is required for follow on tasks.
+          It may be better to use this module with C(check_mode=no) in order to have a valid token that can be used."
   options:
     token_validate:
       description:

diff --git a/plugins/modules/vault_pki_generate_certificate.py b/plugins/modules/vault_pki_generate_certificate.py
@@ -26,9 +26,14 @@
       description: HVAC library reference about the PKI engine.
       link: https://hvac.readthedocs.io/en/stable/usage/secrets_engines/pki.html#generate-certificate
   extends_documentation_fragment:
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.engine_mount
+  attributes:
+    check_mode:
+      support: partial
+      description: In check mode, this module will not contact Vault and will return an empty C(data) field and C(changed) status.
   options:
     alt_names:
       description:

diff --git a/plugins/modules/vault_read.py b/plugins/modules/vault_read.py
@@ -24,6 +24,8 @@
     - ref: community.hashi_vault.hashi_vault lookup <ansible_collections.community.hashi_vault.hashi_vault_lookup>
       description: The official documentation for the C(community.hashi_vault.hashi_vault) lookup plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.attributes.action_group
+    - community.hashi_vault.attributes.check_mode_read_only
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   options:

diff --git a/plugins/modules/vault_token_create.py b/plugins/modules/vault_token_create.py
@@ -27,6 +27,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.token_create
@@ -35,9 +36,13 @@
     - Token creation is a write operation (creating a token persisted to storage), so this module always reports C(changed=True).
     - For the purposes of Ansible playbooks however,
       it may be more useful to set I(changed_when=false) if you are doing idempotency checks against the target system.
-    - In check mode, this module will not create a token, and will instead return a basic structure with an empty token.
-      However, this may not be useful if the token is required for follow on tasks.
-      It may be better to use this module with I(check_mode=no) in order to have a valid token that can be used.
+  attributes:
+    check_mode:
+      support: partial
+      description:
+        - In check mode, this module will not create a token, and will instead return a basic structure with an empty token.
+          However, this may not be useful if the token is required for follow on tasks.
+          It may be better to use this module with I(check_mode=no) in order to have a valid token that can be used.
   options: {}
 """
 

diff --git a/plugins/modules/vault_write.py b/plugins/modules/vault_write.py
@@ -23,13 +23,18 @@
     - The I(data) option is not treated as secret and may be logged. Use the C(no_log) keyword if I(data) contains sensitive values.
     - This module always reports C(changed) status because it cannot guarantee idempotence.
     - Use C(changed_when) to control that in cases where the operation is known to not change state.
+  attributes:
+    check_mode:
+      support: partial
+      description: In check mode, an empty response will be returned and the write will not be performed.
   seealso:
     - ref: community.hashi_vault.vault_write lookup <ansible_collections.community.hashi_vault.vault_write_lookup>
       description: The official documentation for the C(community.hashi_vault.vault_write) lookup plugin.
     - module: community.hashi_vault.vault_read
     - ref: community.hashi_vault.vault_read lookup <ansible_collections.community.hashi_vault.vault_read_lookup>
       description: The official documentation for the C(community.hashi_vault.vault_read) lookup plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.wrapping