From 85048db34e8f92700e3a983be42fd420e46864c1 Mon Sep 17 00:00:00 2001 From: Brian Scholer <1260690+briantist@users.noreply.github.com> Date: Sun, 25 Sep 2022 12:42:07 -0400 Subject: [PATCH] Add docs for `vault_login_token` filter (#263) * add docs for vault_login_token filter * update filter guide * update plugin references * try a different reference * update reference * update descriptions * add license header * add optional_field example, use direct lookup referencing --- docs/docsite/rst/filter_guide.rst | 7 +- plugins/filter/vault_login_token.yml | 98 +++++++++++++++++++++++++++ plugins/lookup/vault_login.py | 2 +- plugins/lookup/vault_token_create.py | 2 +- plugins/modules/vault_login.py | 2 +- plugins/modules/vault_token_create.py | 2 +- 6 files changed, 108 insertions(+), 5 deletions(-) create mode 100644 plugins/filter/vault_login_token.yml diff --git a/docs/docsite/rst/filter_guide.rst b/docs/docsite/rst/filter_guide.rst index 29ddbab78..8cee2b987 100644 --- a/docs/docsite/rst/filter_guide.rst +++ b/docs/docsite/rst/filter_guide.rst @@ -3,6 +3,11 @@ Filter guide ============ +.. note:: + + Filter Plugins are now included with other :ref:`plugin documentation `. + + .. contents:: Filters .. _ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token: @@ -111,7 +116,7 @@ Which produces: "msg": "s.drgLxu6ZtttSVn5Zkoy0huMR" } -This filter is the equivalent of reading into the dictionary directly, but it has the advantage of providing semantic meaning and automatically working against the differing output of both the module and the lookup. +This filter is the equivalent of reading into the dictionary directly, but it has the advantages of providing semantic meaning and automatically working against the differing output of modules and lookups. .. code-block:: yaml+jinja diff --git a/plugins/filter/vault_login_token.yml b/plugins/filter/vault_login_token.yml new file mode 100644 index 000000000..e2946bafe --- /dev/null +++ b/plugins/filter/vault_login_token.yml @@ -0,0 +1,98 @@ +# (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 +--- +DOCUMENTATION: + name: vault_login_token + short_description: Extracts the Vault token from a login or token creation + version_added: 2.2.0 + description: + - Extracts the token value from the structure returned by a Vault token creation operation. + seealso: + - module: community.hashi_vault.vault_login + - module: community.hashi_vault.vault_token_create + - plugin: community.hashi_vault.vault_login + plugin_type: lookup + - plugin: community.hashi_vault.vault_token_create + plugin_type: lookup + - ref: Filter Guide + description: The C(community.hashi_vault) Filter Guide + notes: + - >- + This filter is the same as reading into the I(_input) dictionary directly, + but it provides semantic meaning and automatically works with the differing output of the modules and lookups. + See the Filter guide for more information. + options: + _input: + description: + - A dictionary matching the structure returned by a login or token creation. + type: dict + required: true + optional_field: + description: + - >- + If this field exists in the input dictionary, then the value of that field is used as the I(_input) value. + - >- + The default value deals with the difference between the output of lookup plugins, + and does not need to be changed in most cases. + - See the examples or the Filter guide for more information. + type: string + default: login + author: + - Brian Scholer (@briantist) + +EXAMPLES: | + - name: Set defaults + vars: + ansible_hashi_vault_url: https://vault:9801/ + ansible_hashi_vault_auth_method: userpass + ansible_hashi_vault_username: user + ansible_hashi_vault_password: "{{ lookup('env', 'MY_SECRET_PASSWORD') }}" + module_defaults: + community.hashi_vault.vault_login: + url: '{{ ansible_hashi_vault_url }}' + auth_method: '{{ ansible_hashi_vault_auth_method }}' + username: '{{ ansible_hashi_vault_username }}' + password: '{{ ansible_hashi_vault_password }}' + block: + - name: Perform a login with a lookup and display the token + vars: + login_response: "{{ lookup('community.hashi_vault.vault_login') }}" + debug: + msg: "The token is {{ login_response | community.hashi_vault.vault_login_token }}" + + - name: Perform a login with a module + community.hashi_vault.vault_login: + register: login_response + + - name: Display the token + debug: + msg: "The token is {{ login_response | community.hashi_vault.vault_login_token }}" + + - name: Use of optional_field + vars: + lookup_login_response: "{{ lookup('community.hashi_vault.vault_login') }}" + my_data: + something: somedata + vault_login: "{{ lookup_login_response }}" + + token_from_param: "{{ my_data | community.hashi_vault.vault_login_token(optional_field='vault_login') }}" + token_from_deref: "{{ my_data['vault_login'] | community.hashi_vault.vault_login_token }}" + # if the optional field doesn't exist, the dictionary itself is still checked + unused_optional: "{{ my_data['vault_login'] | community.hashi_vault.vault_login_token(optional_field='missing') }}" + block: + - name: Display the variables + ansible.builtin.debug: + var: '{{ item }}' + loop: + - my_data + - token_from_param + - token_from_deref + - unused_optional + +RETURN: + _value: + description: The token value. + returned: always + sample: s.nnrpog4i5gjizr6b8g1inwj3 + type: string diff --git a/plugins/lookup/vault_login.py b/plugins/lookup/vault_login.py index 5248fbd01..08980ecaa 100644 --- a/plugins/lookup/vault_login.py +++ b/plugins/lookup/vault_login.py @@ -18,7 +18,7 @@ - Performs a login operation against a given path in HashiCorp Vault, returning the login response, including the token. seealso: - module: community.hashi_vault.vault_login - - ref: community.hashi_vault.vault_login_token filter + - ref: community.hashi_vault.vault_login_token filter description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin. notes: - This lookup does not use the term string and will not work correctly in loops. Only a single response will be returned. diff --git a/plugins/lookup/vault_token_create.py b/plugins/lookup/vault_token_create.py index f876c1cc6..9b19ae290 100644 --- a/plugins/lookup/vault_token_create.py +++ b/plugins/lookup/vault_token_create.py @@ -21,7 +21,7 @@ - ref: community.hashi_vault.vault_login lookup description: The official documentation for the C(community.hashi_vault.vault_login) lookup plugin. - module: community.hashi_vault.vault_login - - ref: community.hashi_vault.vault_login_token filter + - ref: community.hashi_vault.vault_login_token filter description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin. notes: - Token creation is a write operation (creating a token persisted to storage), so this module always reports C(changed=True). diff --git a/plugins/modules/vault_login.py b/plugins/modules/vault_login.py index 46df8e0e6..0cc411cec 100644 --- a/plugins/modules/vault_login.py +++ b/plugins/modules/vault_login.py @@ -21,7 +21,7 @@ seealso: - ref: community.hashi_vault.vault_login lookup description: The official documentation for the C(community.hashi_vault.vault_login) lookup plugin. - - ref: community.hashi_vault.vault_login_token filter + - 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.connection diff --git a/plugins/modules/vault_token_create.py b/plugins/modules/vault_token_create.py index 052f67f78..4fd757b06 100644 --- a/plugins/modules/vault_token_create.py +++ b/plugins/modules/vault_token_create.py @@ -24,7 +24,7 @@ - module: community.hashi_vault.vault_login - ref: community.hashi_vault.vault_login lookup description: The official documentation for the C(community.hashi_vault.vault_login) lookup plugin. - - ref: community.hashi_vault.vault_login_token filter + - 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.connection