User guide
The community.hashi_vault collection offers Ansible content for working with HashiCorp Vault.
Note
This guide is a work-in-progress and should not be considered complete. Use it in conjunction with plugin documentation.
Requirements
The content in community.hashi_vault
requires the hvac library.
$ pip install hvac
hvac
version specifics
In general, we recommend using the latest version of hvac
that is supported for your given Python version because that is what we test against. Where possible we will try to list version-specific restrictions here, but this list may not be exhaustive.
hvac
0.7.0+ (for Azure auth and 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)hvac
0.10.12+ (for cert auth)
Other requirements
boto3
(only if loading credentials from a boto session, for example using an AWS profile or IAM role credentials)azure-identity
(only if using a service principal or managed identity)
Retrying failed requests
Via the retries
parameter, you can control what happens when a request to Vault fails, and automatically retry certain requests. Retries are based on the urllib3 Retry class and so all of its options are supported.
Retries are disabled by default.
In community.hashi_vault
you can specify the retries
parameter in two ways:
Set a positive number (integer), where
0
disables retries and any positive number sets the number of tries, with the rest of the retry parameters using the collection defaults.Set a dictionary, where you can set any field that the
Retry
class can be initialized with, in order to fully customize your retry experience.
About the collection defaults
The collection uses its own set of recommended defaults for retries, including which HTTP status codes to retry, which HTTP methods are subject to retries, and the backoff factor used. These defaults are subject to change at any time (in any release) and won’t be considered breaking changes. By setting retries
to a number you are opting in to trust the defaults in the collection. To enable retries with full control over its behavior, be sure to specify a dictionary.
Current Defaults (always check the source code to confirm the defaults in your specific collection version):
status_forcelist:
# https://www.vaultproject.io/api#http-status-codes
# 429 is usually a "too many requests" status, but in Vault it's the default health status response for standby nodes.
- 412 # Precondition failed. Returned on Enterprise when a request can't be processed yet due to some missing eventually consistent data. Should be retried, perhaps with a little backoff.
- 500 # Internal server error. An internal error has occurred, try again later. If the error persists, report a bug.
- 502 # A request to Vault required Vault making a request to a third party; the third party responded with an error of some kind.
- 503 # Vault is down for maintenance or is currently sealed. Try again later.
allowed_methods: null # None allows retries on all methods, including those which may not be considered idempotent, like POST
backoff_factor: 0.3
Any of the Retry
class’s parameters that are not specified in the collection defaults or in your custom dictionary, are initialized using the class’s defaults, with one exception: the raise_on_status
parameter is always set to false
unless you explicitly added it your custom dictionary. The reason is that this lets our error handling look for the expected hvac
exceptions, instead of the Retry
-specfic exceptions. It is recommended that you don’t override this as it may cause unexpected error messages on common failures if they are retried.
Controlling retry warnings
By default, if a retry is performed, a warning will be emitted that shows how many retries are remaining. This can be controlled with the retry_action
option which defaults to warn
. It is recommended to keep this enabled unless you have other processes that will be thrown off by the warning output.
A note about timeouts
Consider setting the timeout
option appropriately when using retries, as a connection timeout doesn’t count toward time between retries (backoff). A long timeout can cause very long delays for a connection that isn’t going to recover, multiplied by number of retries.
However, also consider the type of request being made, and the auth method in use. Because Vault auth methods may have their own dependencies on other systems (an LDAP server, a cloud provider like AWS, a required MFA prompt that depends on a human to respond), the time to complete a request could be quite long, and setting a timeout too short will prevent an otherwise successful request from completing.