Руководство по lookup-плагинам

Запись данных в Vault

Операции, выполняющие запись в Vault, не ограничиваются очевидными действиями, такими как запись значения секрета, создание политики или включение нового метода аутентификации.

Например, любая операция, создающая токен, в том числе любая операция входа, также является операцией записи: токены занимают место в хранилище Vault, а наличие слишком большого количества активных токенов — распространённая причина проблем с производительностью.

Кроме того, некоторые значения в Vault можно «прочитать» только в момент их создания, поэтому единственный способ получить такое значение — получить его в ответе на операцию «записи», в результате которой оно было создано. Распространённый пример — секретные идентификаторы AppRole.

Для Ansible и этой коллекции это означает, что у нас могут быть lookup-плагины, которые неочевидным образом выполняют операции записи (например, vault_login), или lookup-плагины, существование которых изначально может показаться неуместным, например планируемый lookup-плагин vault_write.

Причина в том, что мы часто рассматриваем такие операции как логические операции «чтения», например вход в систему, и хотим использовать их результаты в других выражениях.

Действие вроде vault_write не всегда соответствует этому описанию: его можно использовать для явно выраженной операции записи, например для создания новой политики с помощью lookup-плагина. Но бывают случаи, когда его уместно использовать в контексте lookup, например при «получении» (то есть фактическом создании) нового секретного идентификатора для approle.

Если рассматривать встроенную поддержку методов аутентификации, то любой метод, кроме token или none, превращает каждый lookup, даже vault_read, в операцию, изменяющую состояние и выполняющую запись в Vault. Это также относится ко многим модулям, даже при использовании режима проверки.

Как определить, когда следует использовать lookup-плагины

Поскольку любой lookup-плагин потенциально может выполнять операции записи, очень важно тщательно обдумать, когда использовать lookup-плагин, а когда — модуль или другой плагин. Режим проверки не влияет на lookup-плагины, поэтому во время его выполнения можно выполнить множество операций записи. Однако иногда это может быть необходимо: например, если с помощью lookup-плагина выполняется vault_login для получения токена, который затем используется при вызове модулей, возможно, вы захотите, чтобы это действие выполнялось и в режиме проверки, чтобы вызовы модулей могли правильно проверять необходимые данные.

Некоторые модули, предназначенные главным образом для чтения, например модуль vault_read, при использовании аутентификации, отличной от token или none, всё равно выполняют внутренний вход даже в режиме проверки — это также следует учитывать.

Lookup-плагины и отложенная обработка шаблонов

Возможность lookup-плагинов выполнять операции записи или изменять состояние усугубляется «отложенной» обработкой шаблонов в Ansible, если использовать её неосторожно.

Рассмотрим следующий пример:

- vars:
    token: "{{ lookup('community.hashi_vault.vault_login', auth_method='userpass', username='user', password='pass') | community.hashi_vault.vault_login_token }}"
    secret: "{{ lookup('community.hashi_vault.vault_read', 'secrets/data/my-secret', token=token) }}"
    value_a: "{{ secret.data.data.a }}"
    value_b: "{{ secret.data.data.b }}"
  ansible.builtin.debug:
    msg: "Secret value A is '{{ value_a }}' while value B is '{{ value_b }}'."

Поскольку обработка шаблонов выполняется рекурсивно и отложенно, к сожалению, это не приведёт к однократному входу с повторным использованием токена для однократного чтения секрета, результат которого затем используется при поиске по словарю.

Вместо этого вычисление value_a и value_b каждый раз будет вызывать отдельное вычисление secret, поэтому lookup-плагин будет запущен дважды, и каждый из этих запусков вызовет отдельное вычисление token. В результате будут выполнены два отдельных входа, созданы два токена и прочитан один и тот же секрет дважды.

Если добавить сюда циклы или повторное использование переменных в нескольких задачах, количество запросов к Vault может очень быстро увеличиться, а в случае операций записи — увеличится число создаваемых объектов.

В этом случае удобнее использовать задачи: они выполняются при достижении соответствующего места и не повторяются случайным образом, а возвращаемые ими значения остаются неизменными.

- name: login
  community.hashi_vault.vault_login:
    auth_method: userpass
    username: user
    password: pass
  register: login

- name: get secret
  community.hashi_vault.vault_read:
    token: '{{ login | community.hashi_vault.vault_login_token }}'
    path: 'secrets/data/my-secret'
  register: secret

- vars:
    value_a: "{{ secret.data.data.data.a }}"
    value_b: "{{ secret.data.data.data.b }}"
  ansible.builtin.debug:
    msg: "Secret value A is '{{ value_a }}' while value B is '{{ value_b }}'."

Этот пример выполнит вход и lookup секрета только один раз, хотя он и более многословен. Кроме того, переменные secret и login можно повторно использовать в других задачах, не выполняя дополнительных запросов к Vault.

В обоих примерах также следует учитывать, что задачи выполняются для каждого узла, поэтому количество запросов может снова увеличиться.

В примере с lookup-плагином все запросы выполняются на управляющем узле, а в примере с модулем — на удалённом узле, если только play или задача не направлены на локальный узел.

В обоих случаях вам может быть нужно выполнять запросы для каждого узла, поскольку некоторые переменные, используемые в lookup-плагинах, могут зависеть от конкретного узла: например, могут различаться параметры аутентификации, пути к секретам и даже серверы Vault. Кроме того, при некоторых ограничениях доступа подключение может потребоваться выполнять с удалённого узла, а не с управляющего.

Но если весь доступ к секретам должен выполняться с управляющего узла и запросы не зависят от переменных уровня узла, можно значительно сократить количество запросов, используя run_once, выполняя вызовы Vault в отдельном play, нацеленном только на localhost, и используя ansible.builtin.set_fact либо применяя другие способы.