Вспомогательные программы для учетных данных

Для функций 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

Если вспомогательная программа может предоставить учетные данные для указанного хоста, она должна вывести в поток stdout объект JSON с учетными данными, а затем завершиться с кодом состояния 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. Поддерживаются только стандартные каталоги поиска.