Merge branch 'ansible-collections:main' into develop

.github/workflows/ansible-test.yml

@@ -40,6 +40,7 @@ jobs:
           - stable-2.11
           - stable-2.12
           - stable-2.13
+          - stable-2.14
           - devel
     steps:
 
@@ -67,7 +68,7 @@ jobs:
           # will run on all python versions it supports.
           python-version: 3.9
 
-      # Install the head of the given branch (devel, stable-2.13)
+      # Install the head of the given branch (devel, stable-2.14)
       - name: Install ansible-base (${{ matrix.ansible }})
         run: pip install https://github.com/ansible/ansible/archive/${{ matrix.ansible }}.tar.gz --disable-pip-version-check
 
@@ -116,6 +117,7 @@ jobs:
           - stable-2.11
           - stable-2.12
           - stable-2.13
+          - stable-2.14
           - devel
 
     steps:
@@ -190,6 +192,7 @@ jobs:
           - stable-2.11
           - stable-2.12
           - stable-2.13
+          - stable-2.14
           - devel
         python:
           - '3.6'
@@ -301,7 +304,7 @@ jobs:
       matrix:
         ansible:
           - stable-2.12
-          - stable-2.13
+          - stable-2.14
         python:
           - 3.9
         runner:
@@ -311,11 +314,11 @@ jobs:
           - default
         exclude:
           # To add to the fragility of testing docker stuff on MacOS,
-          # stable-2.13 test containers crash; unsure of exact cause
+          # stable-2.13+ test containers crash; unsure of exact cause
           # but likely due to old versions of the runtimes.
           # We'll just stick to 2.12 for now, better than nothing.
           - runner: macos-12
-            ansible: stable-2.13
+            ansible: stable-2.14
           - runner: ubuntu-latest
             ansible: stable-2.12
 

.github/workflows/docs-push.yml

@@ -38,7 +38,7 @@ jobs:
     if: github.repository == 'ansible-collections/community.hashi_vault'
     permissions:
       contents: read
-    needs: [build-docs]
+    needs: [validate-docs, build-docs]
     name: Publish Ansible Docs
     uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-surge.yml@main
     with:
@@ -52,7 +52,7 @@ jobs:
     if: github.repository == 'ansible-collections/community.hashi_vault'
     permissions:
       contents: write
-    needs: [build-docs]
+    needs: [validate-docs, build-docs]
     name: Publish Ansible Docs
     uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
     with:

CHANGELOG.rst

@@ -5,6 +5,28 @@ community.hashi_vault Release Notes
 .. contents:: Topics
 
 
+v3.3.1
+======
+
+Release Summary
+---------------
+
+No functional changes in this release, this provides updated filter documentation for the public docsite.
+
+v3.3.0
+======
+
+Release Summary
+---------------
+
+With the release of ``hvac`` version ``1.0.0``, we needed to update ``vault_token_create``'s support for orphan tokens.
+The collection's changelog is now viewable in the Ansible documentation site.
+
+Minor Changes
+-------------
+
+- vault_token_create - creation or orphan tokens uses ``hvac``'s new v1 method for creating orphans, or falls back to the v0 method if needed (https://github.com/ansible-collections/community.hashi_vault/issues/301).
+
 v3.2.0
 ======
 

README.md

@@ -17,6 +17,7 @@ If you use the Ansible package and don't update collections independently, use *
 * 2.11
 * 2.12
 * 2.13
+* 2.14
 * devel (latest development commit)
 
 See [the CI configuration](https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/ansible-test.yml) for the most accurate testing information.

changelogs/changelog.yaml

@@ -526,3 +526,23 @@ releases:
     - 296-use-before-assignment.yml
     - 3.2.0.yml
     release_date: '2022-08-21'
+  3.3.0:
+    changes:
+      minor_changes:
+      - vault_token_create - creation or orphan tokens uses ``hvac``'s new v1 method
+        for creating orphans, or falls back to the v0 method if needed (https://github.com/ansible-collections/community.hashi_vault/issues/301).
+      release_summary: 'With the release of ``hvac`` version ``1.0.0``, we needed
+        to update ``vault_token_create``''s support for orphan tokens.
+
+        The collection''s changelog is now viewable in the Ansible documentation site.'
+    fragments:
+    - 3.3.0.yml
+    - 301-orphan-token-handling.yml
+    release_date: '2022-09-19'
+  3.3.1:
+    changes:
+      release_summary: No functional changes in this release, this provides updated
+        filter documentation for the public docsite.
+    fragments:
+    - 3.3.1.yml
+    release_date: '2022-09-25'

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
 

docs/preview/.gitignore

@@ -1,3 +1,7 @@
+# Copyright (c) Ansible Project
+# 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
+
 /temp-rst
 /build
 /rst/collections

docs/preview/antsibull-docs.cfg

@@ -0,0 +1,22 @@
+# Copyright (c) Ansible Project
+# 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
+
+breadcrumbs = true
+indexes = true
+use_html_blobs = false
+
+# You can specify ways to convert a collection name (<namespace>.<name>) to an URL here.
+# You can replace either of <namespace> or <name> by "*" to match all values in that place,
+# or use "*" for the collection name to match all collections. In the URL, you can use
+# {namespace} and {name} for the two components of the collection name. If you want to use
+# "{" or "}" in the URL, write "{{" or "}}" instead. Basically these are Python format
+# strings (https://docs.python.org/3.8/library/string.html#formatstrings).
+collection_url = {
+  * = "https://galaxy.ansible.com/{namespace}/{name}"
+}
+
+# The same wildcard rules and formatting rules as for collection_url apply.
+collection_install = {
+  * = "ansible-galaxy collection install {namespace}.{name}"
+}

docs/preview/build.sh

@@ -1,19 +1,25 @@
 #!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# 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
+
 set -e
 pushd "${BASH_SOURCE%/*}"
 
 # Create collection documentation into temporary directory
 rm -rf temp-rst
 mkdir -p temp-rst
-antsibull-docs collection \
+antsibull-docs \
+    --config-file antsibull-docs.cfg \
+    collection \
     --use-current \
     --dest-dir temp-rst \
     community.hashi_vault
 
 # Copy collection documentation into source directory
-rsync -avc --delete-after temp-rst/collections/ rst/collections/
+rsync -cprv --delete-after temp-rst/collections/ rst/collections/
 
 # Build Sphinx site
-sphinx-build -M html rst build -c .
+sphinx-build -M html rst build -c . -W --keep-going
 
 popd

docs/preview/conf.py

@@ -1,3 +1,7 @@
+# Copyright (c) Ansible Project
+# 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
+
 # This file only contains a selection of the most common options. For a full list see the
 # documentation:
 # http://www.sphinx-doc.org/en/master/config

docs/preview/requirements.txt

@@ -1,4 +1,8 @@
-antsibull-docs
+# Copyright (c) Ansible Project
+# 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
+
+antsibull-docs >= 1.0.0, < 2.0.0
 ansible-pygments
-sphinx
-sphinx-ansible-theme
+sphinx != 5.2.0.post0  # temporary, see https://github.com/ansible-community/antsibull-docs/issues/39, https://github.com/ansible-community/antsibull-docs/issues/40
+sphinx-ansible-theme >= 0.9.0

docs/preview/rst/index.rst

@@ -1,9 +1,13 @@
+# Copyright (c) Ansible Project
+# 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
+
 .. _docsite_root_index:
 
 Ansible collection documentation preview
 ========================================
 
-This docsite contains documentation from ``community.hashi_vault``.
+This docsite contains documentation for ``community.hashi_vault``.
 
 
 .. toctree::

galaxy.yml

@@ -2,7 +2,7 @@
 
 namespace: community
 name: hashi_vault
-version: 3.3.0
+version: 3.4.0
 readme: README.md
 authors:
   - Julie Davila (@juliedavila) <julie(at)davila.io>

plugins/doc_fragments/token_create.py

@@ -15,15 +15,12 @@ class ModuleDocFragment(object):
   orphan:
     description:
       - When C(true), uses the C(/create-orphan) API endpoint, which requires C(sudo) (but not C(root)) to create an orphan.
-      - Implies I(no_parent=true).
-      - B(NOTE:) as of this writing, the underlying endpoint in the C(hvac) library to support this is deprecated and scheduled for removal in C(v1.0.0).
-      - If I(orphan=true) and we cannot access the intended endpoint, the call will be attempted with the C(/create) endpoint, which requires root.
-      - If a replacement is provided in C(hvac), we will add support for it.
+      - With C(hvac>=1.0.0), requires collection version C(>=3.3.0).
     type: bool
     default: false
   no_parent:
     description:
-      - This option only has effect if used by a C(root) or C(sudo) caller, or in combination with I(orphan=true).
+      - This option only has effect if used by a C(root) or C(sudo) caller and only when I(orphan=false).
       - When C(true), the token created will not have a parent.
     type: bool
   no_default_policy:

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

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.