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

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

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

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 Distribution.

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

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

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, позволяющий всегда считать пакет в каталоге кэша допустимым, даже если в файле блокировки зависимостей еще нет подтверждающей его записи:

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