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

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

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

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

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

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

• GitHub

• Bitbucket

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

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

• URL-адреса HTTP

• Бакеты S3

• Бакеты GCS

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

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

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

При использовании протокола 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 мы рекомендуем формат URL с префиксом ssh://, чтобы он соответствовал всем остальным форматам адресов Git, похожим на URL. Вместо этого можно использовать альтернативный синтаксис, «похожий на 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 использовать для доступа к указанному URL-адресу аутентификацию в стиле AWS. Поэтому эта схема может работать и с другими сервисами, имитирующими 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"
}

Для аутентификации в 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}"
}

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