Файл конфигурации CLI (.tofurc или tofu.rc)

Файл конфигурации CLI задаёт пользовательские настройки поведения CLI, которые применяются во всех рабочих каталогах OpenTofu. Он отличается от конфигурации вашей инфраструктуры.

Расположение​

Конфигурацию можно поместить в один файл, расположение которого зависит от операционной системы хоста:

• В Windows файл должен называться tofu.rc и находиться в каталоге %APPDATA% соответствующего пользователя. Физическое расположение этого каталога зависит от версии Windows и конфигурации системы; чтобы узнать его расположение в вашей системе, используйте $env:APPDATA в PowerShell. terraform.rc поддерживается для обратной совместимости. Если существуют оба файла — terraform.rc и tofu.rc, — приоритет будет у более позднего.
• Во всех остальных системах файл должен называться .tofurc (обратите внимание на точку в начале имени) и находиться непосредственно в домашнем каталоге соответствующего пользователя либо называться tofurc и находиться в допустимом каталоге конфигурации базового каталога XDG, например $XDG_CONFIG_HOME/opentofu. .terraformrc поддерживается для обратной совместимости. Если существуют оба файла — .terraformrc и .tofurc, — приоритет будет у последнего. При использовании каталога конфигурации XDG файлы .terraformrc и terraformrc игнорируются.

В Windows имейте в виду, что по умолчанию Проводник Windows скрывает расширения файлов. OpenTofu не распознает файл с именем tofuc.rc.txt как файл конфигурации CLI, даже если Проводник Windows может отображать его имя просто как tofu.rc. Используйте dir в PowerShell или командной строке, чтобы проверить имя файла.

Расположение файла конфигурации CLI OpenTofu также можно указать с помощью TF_CLI_CONFIG_FILE переменной среды. Имя такого файла должно соответствовать шаблону *.tfrc.

Синтаксис файла конфигурации​

В файле конфигурации используется тот же синтаксис HCL, что и в файлах .tf и .tofu, но с другими атрибутами и блоками. В следующем примере показан общий синтаксис; описание каждого параметра приведено в следующем разделе:

plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"

Доступные параметры​

В файле конфигурации CLI можно задать следующие параметры:

• credentials — настраивает учетные данные для использования с облачным бэкендом. Дополнительные сведения см. ниже в разделе Учетные данные.

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

• plugin_cache_dir — включает кэширование плагинов и задает строкой расположение каталога кэша плагинов.

• provider_installation — настраивает методы установки, используемые tofu init при установке плагинов провайдеров. Дополнительные сведения см. ниже в разделе Установка провайдеров.

Учетные данные​

При взаимодействии с сетевыми службами OpenTofu OpenTofu ожидает найти API-токены в файлах конфигурации CLI в блоках credentials:

credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

Если вы запускаете CLI OpenTofu в интерактивном режиме на компьютере с веб-браузером, для получения учетных данных и их автоматического сохранения в конфигурации CLI можно использовать команду tofu login. В противном случае блоки credentials можно создать вручную.

Если вы регулярно пользуетесь службами на нескольких хостах, можно создать несколько блоков credentials. Каждый блок credentials содержит аргумент token, задающий API-токен для этого хоста.

Учетные данные в переменных среды​

Если вы не хотите хранить API-токены непосредственно в конфигурации CLI, можно использовать переменную среды для конкретного хоста. К имени домена следует добавить префикс TF_TOKEN_, заменив точки на символы подчеркивания. Например, значение переменной с именем TF_TOKEN_app_opentofu_org будет использоваться в качестве токена авторизации Bearer, когда CLI отправляет запросы к службам на хост app.opentofu.org.

Имена доменов, содержащие символы не ASCII, необходимо преобразовать в эквивалент в формате Punycode с префиксом ACE. Например, учетные данные с токеном для 例えば.com следует задать в переменной с именем TF_TOKEN_xn--r8j3dr99h_com.

В именах хостов также допустимы дефисы, но обычно они недопустимы в именах переменных, поэтому их можно кодировать двумя символами подчеркивания. Например, токен для доменного имени café.fr можно задать как TF_TOKEN_xn--caf-dma.fr, TF_TOKEN_xn--caf-dma_fr или TF_TOKEN_xn____caf__dma_fr. Если несколько переменных соответствуют одному имени хоста, OpenTofu выберет ту, которая последней определена в таблице переменных операционной системы.

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

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

credentials_helper "example" {
  args = []
}

credentials_helper — это блок конфигурации, который может встречаться в конфигурации CLI не более одного раза. Его метка (выше — "example") задает имя используемой вспомогательной программы для работы с учетными данными. Аргумент args необязателен и позволяет передавать вспомогательной программе дополнительные аргументы, например адрес удаленного хоста, на котором следует искать учетные данные.

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

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

Приоритет источников учетных данных​

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

Установка провайдеров​

По умолчанию плагины провайдеров устанавливаются из реестра провайдеров. Реестр-источник провайдера указывается в адресе его источника, например registry.opentofu.org/hashicorp/aws. Для удобства в наиболее распространенном случае OpenTofu позволяет опускать часть имени хоста для провайдеров в registry.opentofu.org, поэтому можно использовать более короткие адреса общедоступных провайдеров, например hashicorp/aws.

Однако загружать плагин непосредственно из реестра-источника не всегда целесообразно. Например, система, в которой вы запускаете OpenTofu, может не иметь доступа к реестру-источнику из-за ограничений брандмауэра в вашей организации или регионе.

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

Явная настройка методов установки​

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

Общая структура блока provider_installation выглядит следующим образом:

provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}

Каждый вложенный блок внутри блока provider_installation задает один метод установки. Для каждого метода установки можно указать шаблоны include и exclude, определяющие, для каких провайдеров его можно использовать. В приведенном выше примере указано, что любой провайдер, чей реестр-источник находится по адресу example.com, можно установить только из файлового зеркала по адресу /usr/share/terraform/providers, а все остальные провайдеры можно устанавливать только непосредственно из реестров-источников.

Если для метода установки заданы и include, и exclude, приоритет имеют шаблоны исключения. Например, включение registry.opentofu.org/hashicorp/* и исключение registry.opentofu.org/hashicorp/dns приведет к тому, что метод установки будет применяться ко всему пространству имен hashicorp, за исключением hashicorp/dns.

Как и в адресах источников провайдеров в основной конфигурации, для провайдеров, распространяемых через общедоступный реестр OpenTofu, можно опустить префикс registry.opentofu.org/, в том числе при использовании подстановочных знаков. Например, registry.opentofu.org/hashicorp/* и hashicorp/* эквивалентны. */* — это сокращенная запись registry.opentofu.org/*/*, а не */*/*.

Поддерживаются следующие типы методов установки:

• direct: запрашивает сведения о провайдере непосредственно у его реестра-источника и загружает его по сети из указанного этим реестром расположения. Для этого метода не требуются дополнительные аргументы.

• filesystem_mirror: ищет копии провайдеров в каталоге на локальном диске. Для этого метода требуется дополнительный аргумент path, задающий каталог для поиска.

  Указанный каталог должен содержать вложенную структуру каталогов, сегменты пути которой вместе предоставляют метаданные о доступных провайдерах. Поддерживаются две структуры каталогов:

  • Упакованная структура: HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip — это ZIP-архив дистрибутива, полученный из реестра-источника провайдера.
  • Распакованная структура: HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET — это каталог, содержащий результат распаковки ZIP-архива дистрибутива провайдера.

  В обеих структурах VERSION — это строка вида 2.0.0, а TARGET задает конкретную целевую платформу в формате, например, darwin_amd64, linux_arm, windows_amd64 и т. д.

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

  Можно включить несколько блоков filesystem_mirror, чтобы указать несколько каталогов для поиска.

• network_mirror: ищет копии провайдеров на указанном HTTPS-сервере независимо от реестра, к которому они относятся. Для этого метода требуется дополнительный аргумент url, задающий базовый URL зеркала. Он должен использовать схему https: и оканчиваться косой чертой.

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

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

Каталоги локальных зеркал, используемые по умолчанию​

Если в конфигурации CLI вообще нет блока provider_installation, OpenTofu формирует конфигурацию по умолчанию. Она включает набор методов filesystem_mirror, а затем метод direct.

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

• Windows: %APPDATA%/terraform.d/plugins и %APPDATA%/HashiCorp/Terraform/plugins
• Mac OS X: $HOME/.terraform.d/plugins, ~/Library/Application Support/io.terraform/plugins и /Library/Application Support/io.terraform/plugins
• Linux и другие Unix-подобные системы:$HOME/.terraform.d/plugins и opentofu/plugins, расположенные в допустимом каталоге данных базового каталога XDG, например $XDG_DATA_HOME/opentofu/plugins.

Если в текущем рабочем каталоге существует каталог terraform.d/plugins, OpenTofu также включит его независимо от операционной системы. Это поведение меняется при использовании параметра -chdir с командой init. В этом случае OpenTofu проверяет наличие каталога terraform.d/plugins в каталоге запуска, а не в каталоге, указанном с помощью -chdir.

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

Помимо нуля или более неявных блоков filesystem_mirror, OpenTofu также создает неявный блок direct. OpenTofu просканирует все каталоги файловых зеркал, чтобы определить находящиеся в них провайдеры, и автоматически исключит их все из неявного блока direct. (Такое автоматическое поведение exclude применяется только к неявным блокам direct; если вы используете явную конфигурацию provider_installation, необходимые исключения придется указать самостоятельно.)

Кэш плагинов провайдеров​

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

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

Чтобы включить кэширование плагинов, используйте параметр plugin_cache_dir в файле конфигурации CLI. Например:

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

Чтобы OpenTofu мог кэшировать плагины, этот каталог должен существовать заранее; OpenTofu не создаст его самостоятельно.

Обратите внимание: в Windows необходимо использовать прямые косые черты (/), а не обычные обратные косые черты (\), поскольку анализатор файла конфигурации считает обратную косую черту началом escape-последовательности.

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

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"

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

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

Каталог кэша плагинов не должен совпадать с одним из настроенных или подразумеваемых каталогов файловых зеркал, поскольку при работе с одним и тем же каталогом логика управления кэшем конфликтует с логикой файлового зеркала.

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

Разрешение кэшу плагинов провайдеров нарушать файл блокировки зависимостей​

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

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

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

plugin_cache_may_break_dependency_lock_file = true

В качестве альтернативы можно присвоить переменной среды TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE любое значение, кроме пустой строки или 0; это равнозначно указанному выше параметру.

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

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

Переопределения для разработки провайдеров​

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

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

Для удобства разработки провайдеров OpenTofu поддерживает специальный дополнительный блок dev_overrides в блоках provider_installation. Содержимое этого блока фактически переопределяет все остальные настроенные методы установки, поэтому такой блок всегда должен идти первым в последовательности:

provider_installation {

  # Use /home/developer/tmp/terraform-null as an overridden package directory
  # for the hashicorp/null provider. This disables the version and checksum
  # verifications for this provider and forces OpenTofu to look for the
  # null provider plugin in the given directory.
  dev_overrides {
    "hashicorp/null" = "/home/developer/tmp/terraform-null"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, OpenTofu will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

При включенных переопределениях для разработки команда tofu init по-прежнему попытается выбрать подходящую опубликованную версию провайдера для установки и записи в файл блокировки зависимостей для дальнейшего использования. Однако другие команды, например tofu apply, проигнорируют запись hashicorp/null в файле блокировки и вместо этого будут использовать указанный каталог. Когда ваши изменения будут включены в опубликованный выпуск провайдера, можно использовать tofu init -upgrade, чтобы выбрать новую версию в файле блокировки зависимостей и удалить переопределение для разработки.

Путь переопределения для конкретного провайдера должен указывать на каталог, похожий на тот, который был бы включен в файл .zip при распространении провайдера. Как минимум в нем должен быть исполняемый файл с именем, начинающимся, например, с terraform-provider-null, где null — это тип провайдера. Если провайдер использует другие файлы из пакета дистрибутива, их также можно скопировать в каталог переопределения.

Возможно, переопределение для разработки имеет смысл включать только в сеансах командной оболочки, в которых вы непосредственно работаете над разработкой провайдера. В таком случае можно создать локальный файл конфигурации CLI с содержимым, подобным приведенному выше, в каталоге разработки, например назвать его dev.tfrc, а затем использовать переменную среды TF_CLI_CONFIG_FILE, чтобы указать OpenTofu использовать эту локальную конфигурацию CLI вместо конфигурации по умолчанию:

export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc

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

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