Источники модулей

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

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

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

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

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

• GitHub

• Bitbucket

• Универсальные репозитории Git, Mercurial

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

• URL-адреса HTTP

• Бакеты 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"
}

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

В зависимости от типа репозитория 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 — выбор ревизии» в книге о 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».

URL-адреса HTTP​

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

Перед отправкой запроса 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 использовать аутентификацию в стиле AWS при обращении к указанному URL-адресу. Поэтому эта схема может работать и с другими службами, имитирующими API S3, если они обрабатывают аутентификацию так же, как AWS.

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

Установщик модулей ищет учетные данные AWS примерно так же, как AWS CLI, поэтому обычно не требуется дополнительная настройка для использования источников модулей S3, если AWS CLI на вашей системе может получить доступ к тем же объектам S3.

Бакет 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"
}

Установщик модулей использует Google Cloud SDK для аутентификации в GCS. Для настройки учетных данных 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}"
}

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