On this page
community.hashi_vault.vault_read – Perform a read operation against HashiCorp Vault
Note
This plugin is part of the community.hashi_vault collection (version 1.4.1).
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_read
.
New in version 1.4.0: of community.hashi_vault
Synopsis
- Performs a generic read operation against a given path in HashiCorp 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 | Choices/Defaults | Configuration | Comments |
---|---|---|---|
_terms
string / required
|
Vault path(s) to be read.
|
||
auth_method
string
|
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
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
var: ansible_hashi_vault_auth_method
added in 1.2.0 of community.hashi_vault
|
Authentication method to be used.
none auth method was added in collection version 1.2.0 .
cert auth method was added in collection version 1.4.0 .
|
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:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
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
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_CA_CERT
added in 1.2.0 of community.hashi_vault
var: ansible_hashi_vault_ca_cert
added in 1.2.0 of community.hashi_vault
|
Path to certificate to use for authentication.
If not specified by any other means, the
VAULT_CACERT environment variable will be used.
aliases: cacert |
|
cert_auth_private_key
path
added in 1.4.0 of community.hashi_vault
|
ini entries:
[hashi_vault_collection]
env:ANSIBLE_HASHI_VAULT_CERT_AUTH_PRIVATE_KEY
|
For cert auth, path to the private key file to authenticate with, in PEM format.
|
|
cert_auth_public_key
path
added in 1.4.0 of community.hashi_vault
|
ini entries:
[hashi_vault_collection]
env:ANSIBLE_HASHI_VAULT_CERT_AUTH_PUBLIC_KEY
|
For cert auth, path to the certificate file to authenticate with, in PEM format.
|
|
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:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_NAMESPACE
added in 0.2.0 of community.hashi_vault
var: ansible_hashi_vault_namespace
added in 1.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
|
env:ANSIBLE_HASHI_VAULT_PASSWORD
added in 1.2.0 of community.hashi_vault
var: ansible_hashi_vault_password
added in 1.2.0 of community.hashi_vault
|
Authentication password.
|
|
proxies
raw
added in 1.1.0 of community.hashi_vault
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_PROXIES
var: ansible_hashi_vault_proxies
added in 1.2.0 of community.hashi_vault
|
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.
|
|
retries
raw
added in 1.3.0 of community.hashi_vault
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_RETRIES
var: ansible_hashi_vault_retries
|
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
0 , then retries are disabled.
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
Retry class, so it can be used to fully customize retries.
For detailed information on retries, see the collection User Guide.
|
|
retry_action
string
added in 1.3.0 of community.hashi_vault
|
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_RETRY_ACTION
var: ansible_hashi_vault_retry_action
|
Controls whether and how to show messages on retries.
This has no effect if a request is not retried.
|
role_id
string
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
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
var: ansible_hashi_vault_role_id
added in 1.2.0 of community.hashi_vault
|
Vault Role ID or name. Used in
approle , aws_iam_login , and cert auth methods.
For cert auth, if no role_id is supplied, the default behavior is to try all certificate roles and return any one that matches.
|
|
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
var: ansible_hashi_vault_secret_id
added in 1.2.0 of community.hashi_vault
|
Secret ID to be used for Vault AppRole authentication.
|
|
timeout
integer
added in 1.3.0 of community.hashi_vault
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_TIMEOUT
var: ansible_hashi_vault_timeout
|
Sets the connection timeout in seconds.
If not set, then the hvac library's default is used.
|
|
token
string
|
env:ANSIBLE_HASHI_VAULT_TOKEN
added in 0.2.0 of community.hashi_vault
var: ansible_hashi_vault_token
added in 1.2.0 of community.hashi_vault
|
Vault token. Token may be specified explicitly, through the listed [env] vars, 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 var -> ANSIBLE_HASHI_VAULT_TOKEN -> VAULT_TOKEN -> token file .
|
|
token_file
string
|
Default:
".vault-token"
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
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
var: ansible_hashi_vault_token_file
added in 1.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:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
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
var: ansible_hashi_vault_token_path
added in 1.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
|
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_TOKEN_VALIDATE
var: ansible_hashi_vault_token_validate
added in 1.2.0 of community.hashi_vault
|
For token auth, will perform a
lookup-self operation to determine the token's validity before using it.
Disable if your token does not have the lookup-self capability.
|
url
string
|
ini entries:
[hashi_vault_collection]
added in 1.4.0 of community.hashi_vault
env:ANSIBLE_HASHI_VAULT_ADDR
added in 0.2.0 of community.hashi_vault
var: ansible_hashi_vault_url
added in 1.2.0 of community.hashi_vault
var: ansible_hashi_vault_addr
added in 1.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.
If VAULT_ADDR is also not defined then a default of http://127.0.0.1:8200 will be used.
|
|
username
string
|
env:ANSIBLE_HASHI_VAULT_USERNAME
added in 1.2.0 of community.hashi_vault
var: ansible_hashi_vault_username
added in 1.2.0 of community.hashi_vault
|
Authentication user name.
|
|
validate_certs
boolean
|
|
var: ansible_hashi_vault_validate_certs
added in 1.2.0 of community.hashi_vault
|
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.
|
See Also
See also
- community.hashi_vault.vault_read
-
The official documentation on the community.hashi_vault.vault_read module.
- community.hashi_vault.hashi_vault lookup
-
The official documentation for the
community.hashi_vault.hashi_vault
lookup plugin.
Examples
- name: Read a kv2 secret
ansible.builtin.debug:
msg: "{{ lookup('community.hashi_vault.vault_read', 'secret/data/hello', url='https://vault:8201') }}"
- name: Retrieve an approle role ID
ansible.builtin.debug:
msg: "{{ lookup('community.hashi_vault.vault_read', 'auth/approle/role/role-name/role-id', url='https://vault:8201') }}"
- name: Perform multiple reads with a single Vault login
vars:
paths:
- secret/data/hello
- auth/approle/role/role-one/role-id
- auth/approle/role/role-two/role-id
ansible.builtin.debug:
msg: "{{ lookup('community.hashi_vault.vault_read', *paths, auth_method='userpass', username=user, password=pwd) }}"
- name: Perform multiple reads with a single Vault login in a loop
vars:
paths:
- secret/data/hello
- auth/approle/role/role-one/role-id
- auth/approle/role/role-two/role-id
ansible.builtin.debug:
msg: '{{ item }}'
loop: "{{ query('community.hashi_vault.vault_read', *paths, auth_method='userpass', username=user, password=pwd) }}"
- name: Perform multiple reads with a single Vault login in a loop (via with_)
vars:
ansible_hashi_vault_auth_method: userpass
ansible_hashi_vault_username: '{{ user }}'
ansible_hashi_vault_passowrd: '{{ pwd }}'
ansible.builtin.debug:
msg: '{{ item }}'
with_community.hashi_vault.vault_read:
- secret/data/hello
- auth/approle/role/role-one/role-id
- auth/approle/role/role-two/role-id
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 |
The raw result of the read against the given path.
|
Authors
- Brian Scholer (@briantist)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/hashi_vault/vault_read_lookup.html