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

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

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

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

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

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

• GitHub

• Bitbucket

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

• HTTP URL

• Бакеты 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 настройте 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"
}

HTTP URL​

При использовании URL HTTP или HTTPS OpenTofu отправляет на указанный URL запрос GET, в ответ на который можно получить другой адрес источника. Такое перенаправление позволяет использовать 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 в каталоге HOME. Путь к файлу по умолчанию можно изменить, задав переменную среды 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
• 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

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}"
}

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