You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.hashi_vault.vault_ansible_settings lookup – Returns plugin settings (options)

Note

This lookup plugin is part of the community.hashi_vault collection (version 3.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.hashi_vault.

To use it in a playbook, specify: community.hashi_vault.vault_ansible_settings.

New in community.hashi_vault 2.5.0

Synopsis 

Returns a dictionary of options and their values for a given plugin.
This is most useful for using plugin settings in modules and module_defaults, especially when common settings are set in ansible.cfg, in Ansible vars, or via environment variables on the controller.
Options can be filtered by name, and can include or exclude defaults, unset options, and private options.

Terms 

Parameter	Comments
Terms list / elements=string	The names of the options to load. Supports `fnmatch` style wildcards. Prepend any name or pattern with `!` to invert the match. Default: `["*"]`

Keyword parameters 

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('community.hashi_vault.vault_ansible_settings', key1=value1, key2=value2, ...) and query('community.hashi_vault.vault_ansible_settings', key1=value1, key2=value2, ...)

Parameter	Comments
include_default boolean	Include options whose value comes from a default. Choices: `false` ← (default) `true`
include_none boolean	Include options whose value is `None` (this usually means they are unset). Choices: `false` ← (default) `true`
include_private boolean	Include options that begin with underscore `_`. Choices: `false` ← (default) `true`
plugin string	The name of the plugin whose options will be returned. Only lookups are supported. Short names (without a dot `.`) will be fully qualified with `community.hashi_vault`. Default: `"community.hashi_vault.vault_login"`

Notes 

Note

When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('community.hashi_vault.vault_ansible_settings', term1, term2, key1=value1, key2=value2) and query('community.hashi_vault.vault_ansible_settings', term1, term2, key1=value1, key2=value2)
This collection supports some “low precedence” environment variables that get loaded after all other sources, such as VAULT_ADDR.
These environment variables are not supported with this plugin.
If you wish to use them, use the ansible.builtin.env lookup to load them directly when calling a module or setting module_defaults.
Similarly, any options that rely on additional processing to fill in their values will not have that done.
For example, tokens will not be loaded from the token sink file, auth methods will not have their validate methods called.
See the examples for workarounds, but consider using Ansible-specific ways of setting these values instead.

Examples 

### In these examples, we assume an ansible.cfg like this:
# [hashi_vault_collection]
# url = https://config-based-vault.example.com
# retries = 5
### end ansible.cfg

### We assume some environment variables set as well
# ANSIBLE_HASHI_VAULT_URL: https://env-based-vault.example.com
# ANSIBLE_HASHI_VAULT_TOKEN: s.123456789
### end environment variables

# playbook - ansible-core 2.12 and higher
## set defaults for the collection group
- hosts: all
  vars:
    ansible_hashi_vault_auth_method: token
  module_defaults:
    group/community.hashi_vault.vault: "{{ lookup('community.hashi_vault.vault_ansible_settings') }}"
  tasks:
    - name: Get a secret from the remote host with settings from the controller
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret
######

# playbook - ansible any version
## set defaults for a specific module
- hosts: all
  vars:
    ansible_hashi_vault_auth_method: token
  module_defaults:
    community.hashi_vault.vault_kv2_get: "{{ lookup('community.hashi_vault.vault_ansible_settings') }}"
  tasks:
    - name: Get a secret from the remote host with settings from the controller
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret
######

# playbook - ansible any version
## set defaults for several modules
## do not use controller's auth
- hosts: all
  vars:
    ansible_hashi_vault_auth_method: aws_iam
    settings: "{{ lookup('community.hashi_vault.vault_ansible_settings', '*', '!*token*') }}"
  module_defaults:
    community.hashi_vault.vault_kv2_get: '{{ settings }}'
    community.hashi_vault.vault_kv1_get: '{{ settings }}'
  tasks:
    - name: Get a secret from the remote host with some settings from the controller, auth from remote
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret

    - name: Same with kv1
      community.hashi_vault.vault_kv1_get:
        path: app/some/secret
######

# playbook - ansible any version
## set defaults for several modules
## do not use controller's auth
## override returned settings
- hosts: all
  vars:
    ansible_hashi_vault_auth_method: userpass
    plugin_settings: "{{ lookup('community.hashi_vault.vault_ansible_settings', '*', '!*token*') }}"
    overrides:
      auth_method: aws_iam
      retries: '{{ (plugin_settings.retries | int) + 2 }}'
    settings: >-
      {{
        plugin_settings
        | combine(overrides)
      }}
  module_defaults:
    community.hashi_vault.vault_kv2_get: '{{ settings }}'
    community.hashi_vault.vault_kv1_get: '{{ settings }}'
  tasks:
    - name: Get a secret from the remote host with some settings from the controller, auth from remote
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret

    - name: Same with kv1
      community.hashi_vault.vault_kv1_get:
        path: app/some/secret
######

# using a block is similar
- name: Settings
  vars:
    ansible_hashi_vault_auth_method: aws_iam
    settings: "{{ lookup('community.hashi_vault.vault_ansible_settings', '*', '!*token*') }}"
  module_defaults:
    community.hashi_vault.vault_kv2_get: '{{ settings }}'
    community.hashi_vault.vault_kv1_get: '{{ settings }}'
  block:
    - name: Get a secret from the remote host with some settings from the controller, auth from remote
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret

    - name: Same with kv1
      community.hashi_vault.vault_kv1_get:
        path: app/some/secret
#####

# use settings from a different plugin
## when you need settings that are not in the default plugin (vault_login)
- name: Settings
  vars:
    ansible_hashi_vault_engine_mount_point: dept-secrets
    settings: "{{ lookup('community.hashi_vault.vault_ansible_settings', plugin='community.hashi_vault.vault_kv2_get') }}"
  module_defaults:
    community.hashi_vault.vault_kv2_get: '{{ settings }}'
  block:
    - name: Get a secret from the remote host with some settings from the controller, auth from remote
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret
#####

# use settings from a different plugin (on an indivdual call)
## short names assume community.hashi_vault
- name: Settings
  vars:
    ansible_hashi_vault_engine_mount_point: dept-secrets
    settings: "{{ lookup('community.hashi_vault.vault_ansible_settings') }}"
  module_defaults:
    community.hashi_vault.vault_kv2_get: '{{ settings }}'
  block:
    - name: Get a secret from the remote host with some settings from the controller, auth from remote
      community.hashi_vault.vault_kv2_get:
        engine_mount_point: "{{ lookup('community.hashi_vault.vault_ansible_settings', plugin='vault_kv2_get') }}"
        path: app/some/secret
#####

# normally, options with default values are not returned, but can be
- name: Settings
  vars:
    settings: "{{ lookup('community.hashi_vault.vault_ansible_settings') }}"
  module_defaults:
    # we usually want to use the remote host's IAM auth
    community.hashi_vault.vault_kv2_get: >-
      {{
        settings
        | combine({'auth_method': aws_iam})
      }}
  block:
    - name: Use the plugin auth method instead, even if it is the default method
      community.hashi_vault.vault_kv2_get:
        auth_method: "{{ lookup('community.hashi_vault.vault_ansible_settings', 'auth_method', include_default=True) }}"
        path: app/some/secret
#####

# normally, options with None/null values are not returned,
# nor are private options (names begin with underscore _),
# but they can be returned too if desired
- name: Show all plugin settings
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.vault_ansible_settings', include_none=True, include_private=True, include_default=True) }}"
#####

# dealing with low-precedence env vars and token sink loading
## here, VAULT_ADDR is usually used with plugins, but that will not work with vault_ansible_settings.
## additionally, the CLI `vault login` is used before running Ansible, so the token sink is usually used, which also will not work.
- hosts: all
  vars:
    plugin_settings: "{{ lookup('community.hashi_vault.vault_ansible_settings', 'url', 'token*', include_default=True) }}"
    overrides:
      url: "{{ plugin_settings.url | default(lookup('ansible.builtin.env', 'VAULT_ADDR')) }}"
      token: >-
        {{
          plugin_settings.token
          | default(
            lookup(
              'ansible.builtin.file',
              (
                plugin_settings.token_path | default(lookup('ansible.builtin.env', 'HOME')),
                plugin_settings.token_file
              ) | path_join
            )
          )
        }}
      auth_method: token
    settings: >-
      {{
        plugin_settings
        | combine(overrides)
      }}
  module_defaults:
    community.hashi_vault.vault_kv2_get: "{{ lookup('community.hashi_vault.vault_ansible_settings') }}"
  tasks:
    - name: Get a secret from the remote host with settings from the controller
      community.hashi_vault.vault_kv2_get:
        path: app/some/secret
#####

Return Value 

Key	Description
Return value dictionary	A dictionary of the options and their values. Only a single dictionary will be returned, even with multiple terms. Returned: success Sample: `{"retries": 5, "timeout": 20, "token": "s.jRHAoqElnJDx6J5ExYelCDYR", "url": "https://vault.example.com"}`

Authors

Brian Scholer (@briantist)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

Collection links

Issue Tracker Repository (Sources) Discussion, Q&A, troubleshooting Communication

community.hashi_vault.vault_ansible_settings lookup – Returns plugin settings (options)

Synopsis

Terms

Keyword parameters

Notes

See Also

Examples

Return Value