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

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