community.general.hashi_vault – Retrieve secrets from HashiCorp’s Vault
community.general.hashi_vault – Retrieve secrets from HashiCorp’s Vault
Note
This plugin is part of the community.general collection (version 1.3.2).
To install it use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.hashi_vault
.
Synopsis
- Retrieve secrets from HashiCorp’s Vault.
Requirements
The below requirements are needed on the local controller node that executes this lookup.
- hvac (python library)
- hvac 0.7.0+ (for namespace support)
- hvac 0.9.6+ (to avoid all deprecation warnings)
- botocore (only if inferring aws params from boto)
- boto3 (only if using a boto profile)
Parameters
Parameter | Choices/Defaults | Configuration | Comments |
---|---|---|---|
auth_method string |
|
ini entries: [lookup_hashi_vault]auth_method = token added in 0.2.0 of community.general env:VAULT_AUTH_METHOD |
Authentication method to be used.
|
aws_access_key string added in 0.2.0 of community.general |
env:EC2_ACCESS_KEY env:AWS_ACCESS_KEY env:AWS_ACCESS_KEY_ID |
The AWS access key to use.
| |
aws_profile string added in 0.2.0 of community.general |
env:AWS_DEFAULT_PROFILE env:AWS_PROFILE |
The AWS profile
| |
aws_secret_key string added in 0.2.0 of community.general |
env:EC2_SECRET_KEY env:AWS_SECRET_KEY env:AWS_SECRET_ACCESS_KEY |
The AWS secret key that corresponds to the access key.
| |
aws_security_token string added in 0.2.0 of community.general |
env:EC2_SECURITY_TOKEN env:AWS_SESSION_TOKEN env:AWS_SECURITY_TOKEN |
The AWS security token if using temporary access and secret keys. | |
ca_cert string |
Path to certificate to use for authentication.
| ||
jwt string added in 1.3.0 of community.general |
env:ANSIBLE_HASHI_VAULT_JWT |
The JSON Web Token (JWT) to use for JWT authentication to Vault. | |
mount_point string |
Vault mount point, only required if you have a custom mount point. Does not apply to token authentication. | ||
namespace string |
env:VAULT_NAMESPACE added in 1.2.0 of community.general |
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 | |
password string |
Authentication password. | ||
region string added in 0.2.0 of community.general |
env:EC2_REGION env:AWS_REGION |
The AWS region for which to create the connection. | |
return_format string added in 0.2.0 of community.general |
|
Controls how multiple key/value pairs in a path are treated on return.
| |
role_id string |
ini entries: [lookup_hashi_vault]role_id = None added in 0.2.0 of community.general env:VAULT_ROLE_ID |
Vault Role ID. Used in approle and aws_iam_login auth methods. | |
secret string / required |
Vault path to the secret being requested in the format | ||
secret_id string |
env:VAULT_SECRET_ID |
Secret ID to be used for Vault AppRole authentication. | |
token string |
env:VAULT_TOKEN |
Vault token. If using token auth and no token is supplied, explicitly or through env, then the plugin will check for a token file, as determined by | |
token_file string added in 0.2.0 of community.general |
Default: ".vault-token" |
ini entries: [lookup_hashi_vault]token_file = .vault-token
env:VAULT_TOKEN_FILE added in 1.2.0 of community.general |
If no token is specified, will try to read the token from this file in |
token_path string added in 0.2.0 of community.general |
ini entries: [lookup_hashi_vault]token_path = None
env:VAULT_TOKEN_PATH added in 1.2.0 of community.general |
If no token is specified, will try to read the token file from this path. | |
url string |
Default: |
ini entries: [lookup_hashi_vault]url = http://127.0.0.1:8200 added in 0.2.0 of community.general env:VAULT_ADDR |
URL to the Vault service. |
username string |
Authentication user name. | ||
validate_certs boolean |
|
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 |
Notes
Note
- Due to a current limitation in the HVAC library there won’t necessarily be an error if a bad endpoint is specified.
- As of community.general 0.2.0, only the latest version of a secret is returned when specifying a KV v2 path.
- As of community.general 0.2.0, all options can be supplied via term string (space delimited key=value pairs) or by parameters (see examples).
- As of community.general 0.2.0, when
secret
is the first option in the term string,secret=
is not required (see examples).
Examples
- ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello:value token=c975b780-d1be-8016-866b-01d0f9b688a5 url=http://myvault:8200') }}"
- name: Return all secrets from a path
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello token=c975b780-d1be-8016-866b-01d0f9b688a5 url=http://myvault:8200') }}"
- name: Vault that requires authentication via LDAP
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/hello:value auth_method=ldap mount_point=ldap username=myuser password=mypas') }}"
- name: Vault that requires authentication via username and password
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello:value auth_method=userpass username=myuser password=psw url=http://myvault:8200') }}"
- name: Connect to Vault using TLS
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hola:value token=c975b780-d1be-8016-866b-01d0f9b688a5 validate_certs=False') }}"
- name: using certificate auth
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/hi:value token=xxxx url=https://myvault:8200 validate_certs=True cacert=/cacert/path/ca.pem') }}"
- name: Authenticate with a Vault app role
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello:value auth_method=approle role_id=myroleid secret_id=mysecretid') }}"
- name: Return all secrets from a path in a namespace
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello token=c975b780-d1be-8016-866b-01d0f9b688a5 namespace=teama/admins') }}"
# When using KV v2 the PATH should include "data" between the secret engine mount and path (e.g. "secret/data/:path")
# see: https://www.vaultproject.io/api/secret/kv/kv-v2.html#read-secret-version
- name: Return latest KV v2 secret from path
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/data/hello token=my_vault_token url=http://myvault_url:8200') }}"
# The following examples work in collection releases after community.general 0.2.0
- name: secret= is not required if secret is first
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/data/hello token=<token> url=http://myvault_url:8200') }}"
- name: options can be specified as parameters rather than put in term string
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/data/hello', token=my_token_var, url='http://myvault_url:8200') }}"
# return_format (or its alias 'as') can control how secrets are returned to you
- name: return secrets as a dict (default)
ansible.builtin.set_fact:
my_secrets: "{{ lookup('community.general.hashi_vault', 'secret/data/manysecrets', token=my_token_var, url='http://myvault_url:8200') }}"
- ansible.builtin.debug:
msg: "{{ my_secrets['secret_key'] }}"
- ansible.builtin.debug:
msg: "Secret '{{ item.key }}' has value '{{ item.value }}'"
loop: "{{ my_secrets | dict2items }}"
- name: return secrets as values only
ansible.builtin.debug:
msg: "A secret value: {{ item }}"
loop: "{{ query('community.general.hashi_vault', 'secret/data/manysecrets', token=my_token_var, url='http://myvault_url:8200', return_format='values') }}"
- name: return raw secret from API, including metadata
ansible.builtin.set_fact:
my_secret: "{{ lookup('community.general.hashi_vault', 'secret/data/hello:value', token=my_token_var, url='http://myvault_url:8200', as='raw') }}"
- ansible.builtin.debug:
msg: "This is version {{ my_secret['metadata']['version'] }} of hello:value. The secret data is {{ my_secret['data']['data']['value'] }}"
# AWS IAM authentication method
# uses Ansible standard AWS options
- name: authenticate with aws_iam_login
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/hello:value', auth_method='aws_iam_login', role_id='myroleid', profile=my_boto_profile) }}"
# The following examples work in collection releases after community.general 1.3.0
- name: Authenticate with a JWT
ansible.builtin.debug:
msg: "{{ lookup('community.general.hashi_vault', 'secret/hello:value', auth_method='jwt', role_id='myroleid', jwt='myjwt', url='https://myvault:8200')}}"
Return Values
Common return values are documented here, the following are the fields unique to this lookup:
Key | Returned | Description |
---|---|---|
_raw list / elements=dictionary |
success |
secrets(s) requested
|
Authors
- Jonathan Davila (!UNKNOWN)
- Brian Scholer (@briantist)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/hashi_vault_lookup.html