用户指南

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 提示），因此完成请求的时间可能相当长，设置过短的超时将阻止原本成功的请求完成。