community.hashi_vault.vault_kv2_get lookup – Get a secret from HashiCorp Vault’s KV version 2 secret store
Note
This lookup plugin is part of the community.hashi_vault collection (version 2.5.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_kv2_get.
New in version 2.5.0: of community.hashi_vault
Requirements
The below requirements are needed on the local controller node that executes this lookup.
hvac(Python library)For detailed requirements, see the collection requirements page.
Parameters
Parameter |
Comments |
|---|---|
Vault KV path(s) to be read. These are relative to the engine_mount_point, so the mount path should not be included. |
|
Authentication method to be used.
Choices:
Configuration:
|
|
The AWS access key to use. Configuration:
|
|
If specified, sets the value to use for the Configuration:
|
|
The AWS profile Configuration:
|
|
The AWS secret key that corresponds to the access key. Configuration:
|
|
The AWS security token if using temporary access and secret keys. Configuration:
|
|
Path to certificate to use for authentication. If not specified by any other means, the Configuration:
|
|
For Configuration:
|
|
For Configuration:
|
|
The path where the secret backend is mounted. Default: “kv” Configuration:
|
|
The JSON Web Token (JWT) to use for JWT authentication to Vault. Configuration:
|
|
Vault mount point. If not specified, the default mount point for a given auth method is used. Does not apply to token authentication. Configuration:
|
|
Vault namespace where secrets reside. This option requires HVAC 0.7.0+ and Vault 0.11+. Optionally, this may be achieved by prefixing the authentication mount point and/or secret path with the namespace (e.g If environment variable Configuration:
|
|
Authentication password. Configuration:
|
|
URL(s) to the proxies used to access the Vault service. It can be a string or a dict. If it’s a dict, provide the scheme (eg. If it’s a string, provide a single URL that will be used as the proxy for both A string that can be interpreted as a dictionary will be converted to one (see examples). You can specify a different proxy for HTTP and HTTPS resources. If not specified, environment variables from the Requests library are used. Configuration:
|
|
The AWS region for which to create the connection. Configuration:
|
|
Allows for retrying on errors, based on the Retry class in the urllib3 library. This collection defines recommended defaults for retrying connections to Vault. This option can be specified as a positive number (integer) or dictionary. If this option is not specified or the number is A number sets the total number of retries, and uses collection defaults for the other settings. A dictionary value is used directly to initialize the For detailed information on retries, see the collection User Guide. Configuration:
|
|
Controls whether and how to show messages on retries. This has no effect if a request is not retried. Choices:
Configuration:
|
|
Vault Role ID or name. Used in For Configuration:
|
|
Secret ID to be used for Vault AppRole authentication. Configuration:
|
|
Sets the connection timeout in seconds. If not set, then the Configuration:
|
|
Vault token. Token may be specified explicitly, through the listed [env] vars, and also through the If no token is supplied, explicitly or through env, then the plugin will check for a token file, as determined by token_path and token_file. The order of token loading (first found wins) is Configuration:
|
|
If no token is specified, will try to read the token from this file in token_path. Default: “.vault-token” Configuration:
|
|
If no token is specified, will try to read the token_file from this path. Configuration:
|
|
For token auth, will perform a Disable if your token does not have the The default value is The default value will change to Choices:
Configuration:
|
|
URL to the Vault service. If not specified by any other means, the value of the If Configuration:
|
|
Authentication user name. Configuration:
|
|
Controls verification and validation of SSL certificates, mostly you only want to turn off with self signed ones. Will be populated with the inverse of Will default to Choices:
Configuration:
|
|
Specifies the version to return. If not set the latest version is returned. |
See Also
See also
- community.hashi_vault.vault_kv2_get
The official documentation on the community.hashi_vault.vault_kv2_get module.
- community.hashi_vault.vault_kv1_get lookup
The official documentation for the
community.hashi_vault.vault_kv1_getlookup plugin.- community.hashi_vault.vault_kv1_get
The official documentation on the community.hashi_vault.vault_kv1_get module.
- community.hashi_vault Lookup Guide
Guidance on using lookups in
community.hashi_vault.- KV2 Secrets Engine
Documentation for the Vault KV secrets engine, version 2.
Examples
- name: Read a kv2 secret with the default mount point
ansible.builtin.set_fact:
response: "{{ lookup('community.hashi_vault.vault_kv2_get', 'hello', url='https://vault:8201') }}"
# equivalent API path is secret/data/hello
- name: Display the results
ansible.builtin.debug:
msg:
- "Secret: {{ response.secret }}"
- "Data: {{ response.data }} (contains secret data & metadata in kv2)"
- "Metadata: {{ response.metadata }}"
- "Full response: {{ response.raw }}"
- "Value of key 'password' in the secret: {{ response.secret.password }}"
- name: Read version 5 of a kv2 secret with a different mount point
ansible.builtin.set_fact:
response: "{{ lookup('community.hashi_vault.vault_kv2_get', 'hello', version=5, engine_mount_point='custom/kv2/mount', url='https://vault:8201') }}"
# equivalent API path is custom/kv2/mount/data/hello
- name: Assert that the version returned is as expected
ansible.builtin.assert:
that:
- response.metadata.version == 5
- name: Perform multiple kv2 reads with a single Vault login, showing the secrets
vars:
paths:
- hello
- my-secret/one
- my-secret/two
ansible.builtin.debug:
msg: "{{ lookup('community.hashi_vault.vault_kv2_get', *paths, auth_method='userpass', username=user, password=pwd)['secret'] }}"
- name: Perform multiple kv2 reads with a single Vault login in a loop
vars:
paths:
- hello
- my-secret/one
- my-secret/two
ansible.builtin.debug:
msg: '{{ item }}'
loop: "{{ query('community.hashi_vault.vault_kv2_get', *paths, auth_method='userpass', username=user, password=pwd) }}"
- name: Perform multiple kv2 reads with a single Vault login in a loop (via with_), display values only
vars:
ansible_hashi_vault_auth_method: userpass
ansible_hashi_vault_username: '{{ user }}'
ansible_hashi_vault_password: '{{ pwd }}'
ansible.builtin.debug:
msg: '{{ item.values() | list }}'
with_community.hashi_vault.vault_kv2_get:
- hello
- my-secret/one
- my-secret/two
Return Values
Common return values are documented here, the following are the fields unique to this lookup:
Key |
Description |
|---|---|
The result of the read(s) against the given path(s). Returned: success |
|
The Returned: success Sample: {“data”: {“Key1”: “value1”, “Key2”: “value2”}, “metadata”: {“created_time”: “2022-04-21T15:56:58.8525402Z”, “custom_metadata”: null, “deletion_time”: “”, “destroyed”: false, “version”: 2}} |
|
The Returned: success Sample: {“created_time”: “2022-04-21T15:56:58.8525402Z”, “custom_metadata”: null, “deletion_time”: “”, “destroyed”: false, “version”: 2} |
|
The raw result of the read against the given path. Returned: success Sample: {“auth”: null, “data”: {“data”: {“Key1”: “value1”, “Key2”: “value2”}, “metadata”: {“created_time”: “2022-04-21T15:56:58.8525402Z”, “custom_metadata”: null, “deletion_time”: “”, “destroyed”: false, “version”: 2}}, “lease_duration”: 0, “lease_id”: “”, “renewable”: false, “request_id”: “dc829675-9119-e831-ae74-35fc5d33d200”, “warnings”: null, “wrap_info”: null} |
|
The Returned: success Sample: {“Key1”: “value1”, “Key2”: “value2”} |
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