This guide is a work-in-progress and should not be considered complete. Use it in conjunction with plugin documentation.
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.
5.0.0 we are setting a minimum supported version of
The current required minimum
hvac version is
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)
requests>=2.28,<2.29, setting certain options (
namespace) to values that come from lookups will raise an exception, do to Ansible’s marking of the values as “unsafe” for templating. We recommend using
requests>=2.29, which won’t work with Python 3.6.
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.
community.hashi_vault you can specify the
retries parameter in two ways:
Set a positive number (integer), where
0disables 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
Retryclass 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):
# 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
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.