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
ansible-collections · Sep 25, 2022 · 85048db · 85048db
1 parent 65f63ca
commit 85048db
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 5 deletions.
diff --git 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 <plugins_in_community.hashi_vault>`.
+
+
 .. 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
@@ -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 <ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token>
+      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
@@ -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 <ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token>
+    - 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.
   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
@@ -21,7 +21,7 @@
     - ref: community.hashi_vault.vault_login lookup <ansible_collections.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 <ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token>
+    - 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.
   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
@@ -21,7 +21,7 @@
   seealso:
     - ref: community.hashi_vault.vault_login lookup <ansible_collections.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 <ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token>
+    - 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.connection

diff --git 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 <ansible_collections.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 <ansible_collections.community.hashi_vault.docsite.filter_guide.vault_login_token>
+    - 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.connection