diff --git a/changelogs/fragments/197-module-attributes.yml b/changelogs/fragments/197-module-attributes.yml new file mode 100644 index 000000000..2164cfd9c --- /dev/null +++ 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 new file mode 100644 index 000000000..5ac6a5a30 --- /dev/null +++ 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 index 667a11378..0921d6384 100644 --- 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 index e215751f4..923eeb521 100644 --- 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 index 343da2658..07e6d7d69 100644 --- 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 index 0cc411cec..5ff75cfe2 100644 --- a/plugins/modules/vault_login.py +++ b/plugins/modules/vault_login.py @@ -24,6 +24,7 @@ - ref: 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 index ffa3d9038..030ff2f87 100644 --- 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 index 5bbda8dec..fbb2f611b 100644 --- a/plugins/modules/vault_read.py +++ b/plugins/modules/vault_read.py @@ -24,6 +24,8 @@ - ref: 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 index 4fd757b06..fe24cfde4 100644 --- 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 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 index e0833da94..a28c5e54d 100644 --- a/plugins/modules/vault_write.py +++ b/plugins/modules/vault_write.py @@ -23,6 +23,10 @@ - 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 description: The official documentation for the C(community.hashi_vault.vault_write) lookup plugin. @@ -30,6 +34,7 @@ - ref: 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