用户指南

community.hashi_vault 集合提供了用于使用 HashiCorp Vault 的 Ansible 内容。

注意

本指南仍在编写中，不应被视为完整。请结合插件文档使用。

要求 

community.hashi_vault 中的内容需要 hvac 库。

$ pip install hvac

`hvac` 版本具体信息

通常，我们建议使用您的给定 Python 版本支持的最新版本的 hvac，因为这是我们测试所依据的版本。

从 community.hashi_vault 版本 5.0.0 开始，我们设置了 hvac 的最低支持版本。

当前所需的最低 hvac 版本是 1.2.1。

其他要求

boto3 (仅当从 boto 会话加载凭据时，例如使用 AWS 配置文件或 IAM 角色凭据)
azure-identity (仅当使用服务主体或托管身份时)
requests - 使用 requests>=2.28,<2.29, 将某些选项 (token、namespace) 设置为来自查找的值将引发异常，因为 Ansible 将这些值标记为“不安全”以进行模板化。我们建议使用 requests>=2.29，它不适用于 Python 3.6。

重试失败的请求 

通过 retries 参数，您可以控制当对 Vault 的请求失败时会发生什么，并自动重试某些请求。重试基于 urllib3 Retry 类，因此支持其所有选项。

默认情况下禁用重试。

在 community.hashi_vault 中，您可以通过两种方式指定 retries 参数

设置一个正数（整数），其中 0 禁用重试，任何正数都设置重试次数，其余重试参数使用集合默认值。
设置一个字典，您可以在其中设置 Retry 类可以初始化的任何字段，以便完全自定义您的重试体验。

关于集合默认值

该集合对重试使用自己的一组推荐默认值，包括要重试的 HTTP 状态代码、受重试影响的 HTTP 方法以及使用的退避系数。这些默认值可能会随时（在任何版本中）更改，并且不会被视为破坏性更改。通过将 retries 设置为一个数字，您选择信任集合中的默认值。要启用重试并完全控制其行为，请务必指定一个字典。

当前默认值（始终检查源代码以确认您特定集合版本中的默认值）

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

未在集合默认值或您的自定义字典中指定的任何 Retry 类的参数，都使用该类的默认值初始化，但有一个例外：raise_on_status 参数始终设置为 false，除非您显式将其添加到您的自定义字典中。原因是这让我们的错误处理查找预期的 hvac 异常，而不是 Retry 特定的异常。建议您不要覆盖它，因为如果重试，它可能会在常见的故障上导致意外的错误消息。

控制重试警告

默认情况下，如果执行重试，则会发出警告，显示剩余的重试次数。这可以通过 retry_action 选项控制，该选项默认为 warn。建议保持启用此设置，除非您的其他进程会因警告输出而被打断。

关于超时的说明

使用重试时，请考虑适当设置 timeout 选项，因为连接超时不计入重试之间的时间（退避）。长时间的超时可能会导致无法恢复的连接出现非常长的延迟，并且这种延迟会乘以重试次数。

但是，也要考虑正在发出的请求类型以及正在使用的身份验证方法。由于 Vault 身份验证方法可能对其它的系统有依赖性（例如 LDAP 服务器、AWS 等云提供商，需要人工响应的 MFA 提示），因此完成请求的时间可能会很长，如果超时设置得太短，则会阻止原本可以成功的请求完成。