Файл конфигурации 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 Distribution.

  Этот способ похож на 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).

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

provider_installation {
  network_mirror {
    # Our trusted intranet provider mirror
    url              = "https://example.com/"
    include          = ["example.com/*/*"]
    trust_all_hashes = true
  }
}

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

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

Блок конфигурации 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.