Файл конфигурации 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 — настраивает внешнюю вспомогательную программу для хранения и получения учетных данных облачных серверных частей. Дополнительные сведения см. ниже в разделе Вспомогательные программы для учетных данных.

• oci_credentials и default_oci_credentials — настраивают учетные данные для взаимодействия с реестром OCI. Дополнительные сведения см. в разделе Учетные данные реестра OCI.

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

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

• registry_protocols — настраивает некоторые редко используемые параметры, определяющие, как OpenTofu запрашивает метаданные из реестров модулей и провайдеров. Дополнительные сведения см. ниже в разделе Настройки протокола реестра.

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

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

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

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

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

Блоки credentials используются только для протоколов OpenTofu. Учетные данные для реестров OCI можно настроить с помощью блоков oci_credentials, как описано в разделе Учетные данные реестра OCI.

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

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

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

По умолчанию плагины провайдеров устанавливаются из реестра провайдеров. Исходный реестр провайдера задаётся в его адресе источника, например 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, указывающий каталог для поиска.

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

  • Упакованный формат: 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: и заканчиваться косой чертой.

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

• oci_mirror: преобразует адреса источников провайдеров в адреса репозиториев OCI независимо от хоста реестра, к которому они относятся, а затем извлекает их с помощью протокола распространения OCI.

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

  Дополнительные сведения см. в разделе Зеркала провайдеров в реестрах OCI.

Способы direct и network_mirror поддерживают дополнительный аргумент download_retry_count. Если он задан, OpenTofu будет использовать его для повторных попыток загрузки двоичного файла провайдера при возникновении ошибок, допускающих повтор (сброс соединения и ряд ошибок 500).

provider_installation {
  network_mirror {
    url                  = "https://example.com/"
    include              = ["example.com/*/*"]
    download_retry_count = 2
  }
  direct {
    exclude              = ["example.com/*/*"]
    download_retry_count = 3
  }
}

С помощью этого аргумента можно полностью отключить повторные попытки для определенного способа (download_retry_count = 0).

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. Это эквивалентно указанной выше настройке.

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

Мы рекомендуем большинству пользователей не задавать этот параметр. В этом случае 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, в том числе с появлением несовместимых изменений. Поэтому мы рекомендуем использовать переопределения только временно, во время разработки поставщика.

Настройки протокола реестра​

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

registry_protocols {

  # retry_count specifies how many times OpenTofu can
  # retry a registry metadata request when the response
  # is a retry-eligible error.
  #
  # This can also be set using an environment variable:
  #    TF_REGISTRY_DISCOVERY_RETRY=1
  retry_count = 1

  # request_timeout_seconds specifies how long OpenTofu
  # should wait for a response to a registry metadata
  # request, in seconds.
  #
  # This can also be set using an environment variable:
  #    TF_REGISTRY_CLIENT_TIMEOUT=10
  request_timeout_seconds = 10

}

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

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

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