Помощники для учетных данных

Для функций, специфичных для OpenTofu и взаимодействующих с удаленными сетевыми службами, таких как реестры модулей, OpenTofu по умолчанию ищет учетные данные API для этих вызовов в конфигурации CLI.

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

На этой странице рассказывается, как написать и установить помощник для учетных данных. Информацию о настройке уже установленного помощника для учетных данных см. в разделе «Помощники для учетных данных» в конфигурации CLI.

Как OpenTofu находит помощники для учетных данных​

Помощник для учетных данных — это обычная исполняемая программа, установленная в определенном месте и имеющая имя, соответствующее установленным правилам.

Например, помощник для учетных данных под названием «credstore» реализуется в виде исполняемой программы с именем terraform-credentials-credstore (только в Windows — с расширением .exe), установленной в одном из расположений по умолчанию для поиска плагинов.

Как OpenTofu запускает помощники для учетных данных​

Найдя настроенный помощник для учетных данных, OpenTofu будет запускать его для каждого запроса учетных данных, который не может быть удовлетворен блоком credentials в конфигурации CLI.

В следующих примерах будем считать, что настроен помощник для учетных данных «credstore» следующим образом:

credentials_helper "credstore" {
  args = ["--host=credstore.example.com"]
}

OpenTofu запускает программу-помощник, передавая ей все аргументы, указанные в args, а затем глагол и имя хоста, к которому применяется этот глагол. В настоящее время поддерживаются следующие глаголы:

• get: получить учетные данные для указанного имени хоста
• store: сохранить новые учетные данные для указанного имени хоста
• forget: удалить все сохраненные учетные данные для указанного имени хоста

Для представления учетных данных протокол помощника использует объект JSON, содержимое которого соответствует содержимому блоков credentials в конфигурации CLI. Для представления токена API объект содержит свойство с именем «token», значением которого является строка токена:

{
  "token": "example-token-value"
}

В следующих разделах описано ожидаемое поведение для каждого из трех глаголов.

get: получить учетные данные для указанного имени хоста​

Чтобы получить учетные данные для app.example.io, OpenTofu запустит помощник «credstore» следующим образом:

terraform-credentials-credstore --host=credstore.example.com get app.example.io

Если помощник может предоставить учетные данные для указанного хоста, он должен вывести объект JSON с учетными данными в поток stdout, а затем завершить работу с кодом состояния 0, указывающим на успешное выполнение.

Если помощник точно знает, что у него нет учетных данных для указанного хоста, он должен вывести в stdout пустой объект JSON и завершить работу с кодом состояния 0.

Если помощник не может предоставить запрошенные учетные данные по любой другой причине, он должен вывести в поток stderr текстовое сообщение об ошибке, понятное конечному пользователю, а затем завершить работу с ненулевым кодом состояния.

store: сохранить новые учетные данные для указанного имени хоста​

Чтобы сохранить новые учетные данные для app.example.io, OpenTofu запустит помощник «credstore» следующим образом:

terraform-credentials-credstore --host=credstore.example.com store app.example.io

Затем OpenTofu записывает объект JSON с учетными данными в поток stdin программы-помощника. Если помощник может сохранить указанные учетные данные, он должен это сделать, а затем завершить работу с кодом состояния 0, не выводя ничего в stdout или stderr, что указывает на успешное выполнение.

Если помощник не может сохранить указанные учетные данные по какой-либо причине, он все равно должен полностью прочитать данные из stdin до EOF, а затем вывести в поток stderr текстовое сообщение об ошибке, понятное конечному пользователю, прежде чем завершить работу с ненулевым кодом состояния.

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

forget: удалить все сохраненные учетные данные для указанного имени хоста​

Чтобы удалить все существующие учетные данные для app.example.io, OpenTofu запустит помощник «credstore» следующим образом:

terraform-credentials-credstore --host=credstore.example.com forget app.example.io

Для глагола forget объекты JSON с учетными данными не используются.

Если программа-помощник может удалить сохраненные учетные данные для указанного имени хоста или если таких учетных данных уже нет, она должна завершить работу с кодом состояния 0 и ничего не выводить в stdout или stderr.

Если помощник не может удалить сохраненные учетные данные по какой-либо причине, в частности если он не может быть уверен, что учетные данные больше недоступны для получения, программа-помощник должна вывести в поток stderr текстовое сообщение об ошибке, понятное конечному пользователю, а затем завершить работу с ненулевым кодом состояния.

Обработка других команд​

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

Обработка неподдерживаемых свойств объекта с учетными данными​

OpenTofu определяет только свойство token в объектах JSON с учетными данными.

Если помощнику для учетных данных поручено сохранить объект, содержащий свойства, отличные от token, и он не может сохранить их без изменений, он должен вести себя так, как если бы объект нельзя было сохранить, и вернуть ошибку. Он не должен сохранять только значение token, незаметно отбрасывая остальные свойства, поскольку это может изменить смысл объекта с учетными данными.

Если это технически возможно с учетом ограничений целевой системы, помощнику для учетных данных следует по возможности сохранять весь объект JSON как есть для последующего получения. В системах с более строгими ограничениями допустимо сохранять только строку token, если программа отклоняет объекты с другими свойствами, как описано выше.

Установка помощника для учетных данных​

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

Если вы упаковываете помощник для учетных данных для распространения, поместите его в каталог с ожидаемым именем (terraform-credentials-example) и, если формат архива это поддерживает и это имеет смысл для целевой операционной системы, отметьте файл как исполняемый, чтобы повысить вероятность его немедленной работоспособности после извлечения.

При поиске помощников для учетных данных OpenTofu не учитывает аргумент -plugin-dir для tofu init, поскольку учетные данные используются также другими командами, которые можно запускать до tofu init. Поддерживаются только расположения поиска по умолчанию.