community.hashi_vault.hashi_vault – Retrieve secrets from HashiCorp’s Vault¶

Note

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

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

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

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

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 most deprecation warnings)
hvac 0.10.5+ (for JWT auth)
hvac 0.10.6+ (to avoid deprecation warning for AppRole)
botocore (only if inferring aws params from boto)
boto3 (only if using a boto profile)

Parameters ¶

Parameter	Choices/Defaults	Configuration	Comments
auth_method string	Choices: token ← userpass ldap approle aws_iam_login jwt	ini entries: [lookup_hashi_vault] auth_method = token env:VAULT_AUTH_METHOD Removed in: version 2.0.0 Why: standardizing environment variables Alternative: ANSIBLE_HASHI_VAULT_AUTH_METHOD env:ANSIBLE_HASHI_VAULT_AUTH_METHOD added in 0.2.0 of community.hashi_vault	Authentication method to be used.
aws_access_key string		env:EC2_ACCESS_KEY env:AWS_ACCESS_KEY env:AWS_ACCESS_KEY_ID	The AWS access key to use. aliases: aws_access_key_id
aws_iam_server_id string added in 0.2.0 of community.hashi_vault		ini entries: [lookup_hashi_vault] aws_iam_server_id = None env:ANSIBLE_HASHI_VAULT_AWS_IAM_SERVER_ID	If specified, sets the value to use for the `X-Vault-AWS-IAM-Server-ID` header as part of `GetCallerIdentity` request.
aws_profile string		env:AWS_DEFAULT_PROFILE env:AWS_PROFILE	The AWS profile aliases: boto_profile
aws_secret_key string		env:EC2_SECRET_KEY env:AWS_SECRET_KEY env:AWS_SECRET_ACCESS_KEY	The AWS secret key that corresponds to the access key. aliases: aws_secret_access_key
aws_security_token string		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. aliases: cacert
jwt string		env:ANSIBLE_HASHI_VAULT_JWT	The JSON Web Token (JWT) to use for JWT authentication to Vault.
mount_point string			Vault mount point. If not specified, the default mount point for a given auth method is used. Does not apply to token authentication.
namespace string		ini entries: [lookup_hashi_vault] namespace = None added in 0.2.0 of community.hashi_vault env:ANSIBLE_HASHI_VAULT_NAMESPACE added in 0.2.0 of community.hashi_vault	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 `mynamespace/secret/mysecret`). If environment variable `VAULT_NAMESPACE` is set, its value will be used last among all ways to specify namespace.
password string			Authentication password.
proxies raw added in 1.1.0 of community.hashi_vault		ini entries: [lookup_hashi_vault] proxies = None env:ANSIBLE_HASHI_VAULT_PROXIES	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. `http` or `https`) as the key, and the URL as the value. If it's a string, provide a single URL that will be used as the proxy for both `http` and `https` schemes. 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.
region string		env:EC2_REGION env:AWS_REGION	The AWS region for which to create the connection.
return_format string	Choices: dict ← values raw		Controls how multiple key/value pairs in a path are treated on return. `dict` returns a single dict containing the key/value pairs. `values` returns a list of all the values only. Use when you don't care about the keys. `raw` returns the actual API result (deserialized), which includes metadata and may have the data nested in other keys. aliases: as
role_id string		ini entries: [lookup_hashi_vault] role_id = None env:VAULT_ROLE_ID Removed in: version 2.0.0 Why: standardizing environment variables Alternative: ANSIBLE_HASHI_VAULT_ROLE_ID env:ANSIBLE_HASHI_VAULT_ROLE_ID added in 0.2.0 of community.hashi_vault	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 `path[:field]`.
secret_id string		env:VAULT_SECRET_ID Removed in: version 2.0.0 Why: standardizing environment variables Alternative: ANSIBLE_HASHI_VAULT_SECRET_ID env:ANSIBLE_HASHI_VAULT_SECRET_ID added in 0.2.0 of community.hashi_vault	Secret ID to be used for Vault AppRole authentication.
token string		env:ANSIBLE_HASHI_VAULT_TOKEN added in 0.2.0 of community.hashi_vault	Vault token. Token may be specified explicitly, through the listed env var, and also through the `VAULT_TOKEN` env var. 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 `token param -> ANSIBLE_HASHI_VAULT_TOKEN -> VAULT_TOKEN -> token file`.
token_file string	Default: ".vault-token"	ini entries: [lookup_hashi_vault] token_file = .vault-token env:VAULT_TOKEN_FILE Removed in: version 2.0.0 Why: standardizing environment variables Alternative: ANSIBLE_HASHI_VAULT_TOKEN_FILE env:ANSIBLE_HASHI_VAULT_TOKEN_FILE added in 0.2.0 of community.hashi_vault	If no token is specified, will try to read the token from this file in token_path.
token_path string		ini entries: [lookup_hashi_vault] token_path = None env:VAULT_TOKEN_PATH Removed in: version 2.0.0 Why: standardizing environment variables Alternative: ANSIBLE_HASHI_VAULT_TOKEN_PATH env:ANSIBLE_HASHI_VAULT_TOKEN_PATH added in 0.2.0 of community.hashi_vault	If no token is specified, will try to read the token_file from this path.
token_validate boolean added in 0.2.0 of community.hashi_vault	Choices: no yes ←	ini entries: [lookup_hashi_vault] token_validate = yes env:ANSIBLE_HASHI_VAULT_TOKEN_VALIDATE	For token auth, will perform a `lookup-self` operation to determine the token's validity before using it. Disable if your token doesn't have the `lookup-self` capability.
url string	Default: "http://127.0.0.1:8200"	ini entries: [lookup_hashi_vault] url = http://127.0.0.1:8200 env:ANSIBLE_HASHI_VAULT_ADDR added in 0.2.0 of community.hashi_vault	URL to the Vault service. If not specified by any other means, the value of the `VAULT_ADDR` environment variable will be used.
username string			Authentication user name.
validate_certs boolean	Choices: no yes		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 `VAULT_SKIP_VERIFY` if that is set and validate_certs is not explicitly provided. Will default to `true` if neither validate_certs or `VAULT_SKIP_VERIFY` are set.

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.hashi_vault 0.1.0, only the latest version of a secret is returned when specifying a KV v2 path.
As of community.hashi_vault 0.1.0, all options can be supplied via term string (space delimited key=value pairs) or by parameters (see examples).
As of community.hashi_vault 0.1.0, when secret is the first option in the term string, secret= is not required (see examples).

Examples ¶

- ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.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.hashi_vault.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.hashi_vault.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.hashi_vault.hashi_vault', 'secret=secret/hola:val auth_method=userpass username=myuser password=psw url=http://vault:8200') }}"

- name: Connect to Vault using TLS
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.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.hashi_vault.hashi_vault', 'secret/hi:val token=xxxx url=https://vault:8200 validate_certs=True cacert=/cacert/path/ca.pem') }}"

- name: Authenticate with a Vault app role
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.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.hashi_vault.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.hashi_vault.hashi_vault', 'secret=secret/data/hello token=my_vault_token url=http://myvault_url:8200') }}"

# The following examples show more modern syntax, with parameters specified separately from the term string.

- name: secret= is not required if secret is first
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.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.hashi_vault.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.hashi_vault.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.hashi_vault.hashi_vault', 'secret/data/manysecrets', token=my_token_var, url='http://vault_url:8200', return_format='values') }}"

- name: return raw secret from API, including metadata
  ansible.builtin.set_fact:
    my_secret: "{{ lookup('community.hashi_vault.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.hashi_vault.hashi_vault', 'secret/hello:value', auth_method='aws_iam_login', role_id='myroleid', profile=my_boto_profile) }}"

# JWT auth

- name: Authenticate with a JWT
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', 'secret/hola:val', auth_method='jwt', role_id='myroleid', jwt='myjwt', url='https://vault:8200') }}"

# Disabling Token Validation
# Use this when your token does not have the lookup-self capability. Usually this is applied to all tokens via the default policy.
# However you can choose to create tokens without applying the default policy, or you can modify your default policy not to include it.
# When disabled, your invalid or expired token will be indistinguishable from insufficent permissions.

- name: authenticate without token validation
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', 'secret/hello:value', token=my_token, token_validate=False) }}"

# Use a proxy

- name: use a proxy with login/password
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=... token=... url=https://... proxies=https://user:pass@myproxy:8080') }}"

- name: 'use a socks proxy (need some additional dependencies, see: https://requests.readthedocs.io/en/master/user/advanced/#socks )'
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=... token=... url=https://... proxies=socks5://myproxy:1080') }}"

- name: use proxies with a dict (as param)
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', '...', proxies={'http': 'http://myproxy1', 'https': 'http://myproxy2'}) }}"

- name: use proxies with a dict (as param, pre-defined var)
  vars:
    prox:
      http: http://myproxy1
      https: https://myproxy2
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', '...', proxies=prox }}"

- name: use proxies with a dict (in the term string, Ansible key=value syntax)
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', '... proxies=http=http://myproxy1,https=http://myproxy2') }}"

- name: use proxies with a dict (in the term string, JSON syntax)
  ansible.builtin.debug:
    msg: "{{ lookup('community.hashi_vault.hashi_vault', '... proxies={\"http\":\"http://myproxy1\",\"https\":\"http://myproxy2\"}') }}"

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) <jdavila(at)ansible.com>
Brian Scholer (@briantist)

community.hashi_vault.hashi_vault – Retrieve secrets from HashiCorp’s Vault¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶