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

Для функций 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, а затем завершиться с кодом состояния ноль, указывающим на успешное выполнение.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Установка вспомогательного средства для учетных данных​

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

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

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