Руководство пользователя

Особенности версии hvac

В целом мы рекомендуем использовать последнюю версию hvac, поддерживаемую вашей версией Python, поскольку именно с ней мы проводим тестирование.

Начиная с версии 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) в значения, полученные из lookup-запросов, вызовет исключение из-за того, что Ansible помечает эти значения как «небезопасные» для шаблонной подстановки. Мы рекомендуем использовать requests>=2.29, который не работает с Python 3.6.

О значениях по умолчанию коллекции

Коллекция использует собственный набор рекомендуемых значений по умолчанию для повторных попыток, включая 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, требующего ответа человека), выполнение запроса может занять довольно много времени. Слишком короткий тайм-аут не позволит завершиться запросу, который в противном случае выполнился бы успешно.