Исходный код модулей

Аргумент source в блоке module указывает OpenTofu, где найти исходный код нужного дочернего модуля.

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

Установщик модулей поддерживает установку из нескольких типов источников.

• Локальные пути

• Реестр модулей

• GitHub

• Bitbucket

• Репозитории Git и Mercurial

• Репозитории OCI Distribution

• HTTP URL

• Бакеты S3

• Бакеты GCS

• Модули во вложенных каталогах пакета

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

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

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

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

Локальные пути​

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

module "consul" {
  source = "./consul"
}

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

Локальные пути отличаются тем, что их не «устанавливают» так же, как другие источники: файлы уже находятся на локальном диске (возможно, в результате установки родительского модуля), поэтому их можно использовать напрямую. Исходный код автоматически обновляется при обновлении родительского модуля.

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

Реестр модулей​

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

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

Вы также можете использовать приватный реестр — через TACOS (программное обеспечение для автоматизации и совместной работы с TF) или запустив собственную службу, реализующую протокол реестра модулей.

На модули из общедоступного реестра можно ссылаться с помощью адреса источника в формате <NAMESPACE>/<NAME>/<PROVIDER>. На информационной странице каждого модуля на сайте реестра указан точный адрес.

module "consul" {
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}

В приведённом выше примере используется модуль Consul для AWS из общедоступного реестра.

Для модулей, размещённых в других реестрах, добавьте к адресу источника дополнительную часть <HOSTNAME>/ с именем хоста приватного реестра:

module "consul" {
  source = "app.terraform.io/example-corp/k8s-cluster/azurerm"
  version = "1.1.0"
}

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

Подробнее о реестре см. в документации по реестру модулей.

Для доступа к модулям из приватного реестра может потребоваться настроить токен доступа в конфигурации CLI. Используйте то же имя хоста, что и в строке источника модуля. Для приватного реестра в TACOS (программном обеспечении для автоматизации и совместной работы с TF) используйте тот же токен аутентификации, что и для API или клиентов командной строки.

GitHub​

OpenTofu распознаёт URL github.com без префикса и автоматически интерпретирует их как источники Git-репозитория.

module "consul" {
  source = "github.com/hashicorp/example"
}

Схема адреса выше клонирует репозиторий по HTTPS. Чтобы клонировать его по SSH, используйте следующий формат:

module "consul" {
  source = "git@github.com:hashicorp/example.git"
}

Эти схемы GitHub считаются удобными псевдонимами для общей схемы адреса Git-репозитория, поэтому для них используются те же учетные данные и поддерживается аргумент ref для выбора конкретной ревизии. В частности, для доступа к приватным репозиториям потребуется настроить учетные данные.

Bitbucket​

OpenTofu распознаёт URL bitbucket.org без префикса и автоматически интерпретирует их как репозитории BitBucket:

module "consul" {
  source = "bitbucket.org/example-corp/tofu-consul-aws"
}

Это сокращённое обозначение работает только для общедоступных репозиториев, поскольку OpenTofu должен обращаться к API BitBucket, чтобы определить, использует ли указанный репозиторий Git или Mercurial.

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

Универсальный Git-репозиторий​

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

Например, для использования HTTPS или SSH:

module "vpc" {
  source = "git::https://example.com/vpc.git"
}

module "storage" {
  source = "git::ssh://username@example.com/storage.git"
}

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

При использовании протокола SSH автоматически применяются все настроенные ключи SSH. Это самый распространённый способ доступа к непубличным Git-репозиториям из автоматизированных систем, поскольку он позволяет обращаться к приватным репозиториям без интерактивных запросов.

При использовании протокола HTTP/HTTPS или любого другого протокола с учетными данными в виде имени пользователя и пароля настройте хранилище учетных данных Git, чтобы выбрать подходящий для вашей среды источник учетных данных.

Выбор ревизии​

По умолчанию OpenTofu клонирует репозиторий и использует его ветку по умолчанию (на которую ссылается HEAD). Это можно изменить с помощью аргумента ref. Значением аргумента ref может быть любая ссылка, допустимая для команды git checkout, например имя ветки, хеш SHA-1 (короткий или полный) либо имя тега. Полный список возможных значений см. в разделе Git Tools — выбор ревизии в книге Git.

# select a specific tag
module "vpc" {
  source = "git::https://example.com/vpc.git?ref=v1.2.0"
}

# directly select a commit using its SHA-1 hash
module "storage" {
  source = "git::https://example.com/storage.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

Поверхностное клонирование​

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

Аргумент URL depth соответствует аргументу --depth команды git clone: он указывает Git создать поверхностный клон, ограничив историю заданным количеством коммитов.

Однако, поскольку при поверхностном клонировании требуется другое поведение протокола Git, при задании аргумента depth OpenTofu передаёт ваш аргумент ref, если он указан, аргументу --branch команды git clone. Это означает, что необходимо указать именованную ветку или тег, известные удалённому репозиторию; идентификаторы коммитов использовать нельзя.

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

Синтаксис адреса «в стиле scp»​

При использовании Git через SSH мы рекомендуем для единообразия с остальными адресами Git в формате URL использовать форму URL с префиксом ssh://. Вместо этого можно выбрать альтернативный синтаксис «в стиле scp»; в этом случае необходимо опустить часть схемы ssh:// и указать только часть git::. Например:

module "storage" {
  source = "git::username@example.com:storage.git"
}

Если используется схема URL ssh://, OpenTofu считает, что двоеточие обозначает начало номера порта, а не пути. Это соответствует тому, как Git интерпретирует эти формы, за исключением специфичного для OpenTofu префикса выбора git::.

Универсальный репозиторий Mercurial​

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

module "vpc" {
  source = "hg::http://example.com/vpc.hg"
}

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

При использовании протокола SSH автоматически применяются все настроенные ключи SSH. Это самый распространённый способ доступа к непубличным репозиториям Mercurial из автоматизированных систем, поскольку он позволяет обращаться к приватным репозиториям без интерактивных запросов.

Выбор ревизии​

С помощью необязательного аргумента ref можно выбрать ветку или тег, отличные от используемых по умолчанию:

module "vpc" {
  source = "hg::http://example.com/vpc.hg?ref=v1.2.0"
}

Репозиторий OCI Distribution​

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

module "example" {
  source = "oci://example.com/repository-name"
}

Имя домена, указанное сразу после префикса oci://, — это домен реестра OCI. Остальная часть адреса задаёт имя конкретного репозитория в этом реестре.

Если указанный реестр OCI требует учетных данных для аутентификации, см. раздел «Учетные данные реестра OCI».

Выбор тега или дайджеста​

По умолчанию OpenTofu пытается получить артефакт, связанный с удалённым тегом «latest». Выбрать другой артефакт можно с помощью одного из следующих аргументов строки запроса:

• tag задаёт другое имя тега.
• digest напрямую задаёт дайджест манифеста нужного артефакта, полностью игнорируя теги, определённые в репозитории.

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

Например, чтобы выбрать тег с именем v1.0.0:

module "example" {
  source = "oci://example.com/repository-name?tag=v1.0.0"
}

Создание артефакта пакета модуля​

Подробнее о структуре манифеста, которую OpenTofu ожидает для артефактов пакетов модулей, см. в разделе «Пакеты модулей в реестрах OCI».

HTTP URL​

При использовании URL HTTP или HTTPS OpenTofu отправит запрос GET по указанному URL, который может вернуть другой адрес источника. Это перенаправление позволяет использовать HTTP URL как своего рода «красивую ссылку» на более сложный адрес источника модуля.

Перед отправкой запроса GET OpenTofu добавит к указанному URL дополнительный аргумент строки запроса tofu-get=1, позволяя серверу при необходимости возвращать другой результат, когда запрос поступает от OpenTofu.

Если запрос завершился успешно (код состояния в диапазоне 200), OpenTofu ищет следующий адрес в указанном ниже порядке:

• Значение поля заголовка ответа с именем X-Terraform-Get.

• Если ответ представляет собой HTML-страницу, элемент meta с именем tofu-get:

  <meta name="tofu-get" content="github.com/hashicorp/example" />

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

Если для доступа по URL HTTP/HTTPS требуются учетные данные, используйте файл .netrc для их настройки. По умолчанию OpenTofu ищет файл .netrc в домашнем каталоге. Однако расположение файла в файловой системе можно изменить, задав переменную среды NETRC. Сведения о формате .netrc см. в документации по его использованию в curl.

Загрузка архивов по HTTP​

В особом случае, если OpenTofu обнаружит в URL распространённое расширение файла, соответствующее формату архива, он пропустит описанное выше специальное перенаправление tofu-get=1 и вместо этого напрямую использует содержимое указанного архива как исходный код модуля:

module "vpc" {
  source = "https://example.com/vpc-module.zip"
}

Для этого особого режима OpenTofu распознаёт следующие расширения:

• zip
• tar.bz2 и tbz2
• tar.gz и tgz
• tar.xz и txz

Если URL не имеет одного из этих расширений, но всё же указывает на архив, используйте аргумент archive, чтобы принудительно включить такую интерпретацию:

module "vpc" {
  source = "https://example.com/vpc-module?archive=zip"
}

Бакет S3​

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

module "consul" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/vpc.zip"
}

Префикс s3:: указывает OpenTofu использовать для доступа к заданному URL аутентификацию в стиле AWS. Поэтому эта схема может работать и с другими службами, имитирующими API S3, если они обрабатывают аутентификацию так же, как AWS.

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

Установщик модулей ищет учетные данные AWS в следующих местах, отдавая предпочтение источникам, расположенным выше в списке:

• Переменные среды AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY.
• Профиль по умолчанию в файле .aws/credentials в домашнем каталоге.
• При запуске на экземпляре EC2 — временные учетные данные, связанные с профилем экземпляра IAM.

Бакет GCS​

В качестве источников модулей можно использовать архивы, хранящиеся в Google Cloud Storage. Для этого укажите специальный префикс gcs::, за которым следует URL объекта в бакете GCS.

Например:

• gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE
• gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip

module "consul" {
  source = "gcs::https://www.googleapis.com/storage/v1/modules/foomodule.zip"
}

Для аутентификации в GCS установщик модулей использует Google Cloud SDK. Чтобы задать учетные данные Google Cloud Platform, можно воспользоваться одним из следующих способов:

• Задайте для переменной среды GOOGLE_OAUTH_ACCESS_TOKEN необработанный токен доступа OAuth Google Cloud Platform.
• Укажите путь к файлу ключа учетной записи службы в переменной среды GOOGLE_APPLICATION_CREDENTIALS.
• Если вы запускаете OpenTofu на экземпляре GCE, учетные данные по умолчанию доступны автоматически. Подробнее см. в разделе «Создание и включение учетных записей служб» для экземпляров.
• На своём компьютере можно сделать свою учетную запись Google доступной, выполнив команду gcloud auth application-default login.

Модули во вложенных каталогах пакета​

Если источником модуля является репозиторий системы управления версиями или архив (обобщённо — «пакет»), сам модуль может находиться во вложенном каталоге относительно корня пакета.

Специальный синтаксис с двойным слешем интерпретируется OpenTofu как указание на то, что оставшаяся часть пути задаёт вложенный каталог в пакете. Например:

• hashicorp/consul/aws//modules/consul-cluster
• git::https://example.com/network.git//modules/vpc
• oci://example.com/repository-name//modules/vpc
• https://example.com/network-module.zip//modules/vpc
• s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/network.zip//modules/vpc

Если адрес источника содержит аргументы, например аргумент ref, поддерживаемый источниками из систем управления версиями, часть с вложенным каталогом должна располагаться перед этими аргументами:

• git::https://example.com/network.git//modules/vpc?ref=v1.2.0
• github.com/hashicorp/example//modules/vpc?ref=v1.2.0
• oci://example.com/repository-name//modules/vpc?tag=v1.2.0

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

Поддержка вычисления переменных и локальных значений​

По мере роста сложности и требований проекта целесообразно рассмотреть возможность использования локальных значений и переменных в полях источника и версии модуля.

Многие организации используют для модулей шаблон монорепозитория:

locals {
	modules_repo = "github.com/myorg/tofu-modules/"
	modules_version = "?ref=v1.20.4"
}

module "storage" {
  source = "${local.modules_repo}/storage${local.modules_version}"
}

module "compute" {
  source = "${local.modules_repo}/compute${local.modules_version}"
}

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