Блоки модулей

Модуль — это контейнер для нескольких ресурсов, используемых вместе.

В каждой конфигурации OpenTofu есть как минимум один модуль, называемый корневым модулем. Он состоит из ресурсов, определённых в файлах .tf и .tofu в основном рабочем каталоге.

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

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

Вызов дочернего модуля​

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

module "servers" {
  source = "./app-cluster"

  servers = 5
}

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

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

В теле блока (между { и }) указываются аргументы модуля. В вызовах модулей используются следующие типы аргументов:

• Аргумент source обязателен для всех модулей.

• Аргумент version рекомендуется использовать для модулей из реестра.

• Большинство остальных аргументов соответствуют входным переменным, определённым модулем. (Аргумент servers в приведённом выше примере — один из них.)

• OpenTofu определяет несколько других метааргументов, которые можно использовать со всеми модулями, включая for_each и depends_on.

Источник​

Для всех модулей обязателен аргумент source — метааргумент, определённый OpenTofu. Его значением может быть путь к локальному каталогу с файлами конфигурации модуля или источник удалённого модуля, который OpenTofu должен скачать и использовать. Дополнительные сведения о возможных значениях этого аргумента см. в разделе Источники модулей.

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

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

Версия​

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

Используйте аргумент version в блоке module, чтобы указать версии:

module "consul" {
  source  = "hashicorp/consul/aws"
  version = "0.0.5"

  servers = 3
}

Аргумент version принимает строку ограничения версии. OpenTofu использует самую новую из установленных версий модуля, соответствующую ограничению; если подходящих установленных версий нет, он скачает самую новую версию, соответствующую ограничению.

Ограничения версий поддерживаются только для модулей, установленных из реестра модулей, например из публичного реестра OpenTofu или любого частного реестра модулей TACOS (программного обеспечения для автоматизации и совместной работы с Terraform). Другие источники модулей могут предоставлять собственные механизмы управления версиями непосредственно в строке источника или вовсе не поддерживать версии. В частности, для модулей, взятых из локальных путей файловой системы, version не поддерживается: поскольку они загружаются из того же репозитория исходного кода, их версия всегда совпадает с версией вызывающего модуля.

Метааргументы​

Помимо source и version, OpenTofu определяет ещё несколько необязательных метааргументов, имеющих особое значение для всех модулей. Более подробно они описаны на следующих страницах:

• count — создаёт несколько экземпляров модуля из одного блока module. Подробнее см. на странице count.

• for_each — создаёт несколько экземпляров модуля из одного блока module. Подробнее см. на странице for_each.

• providers — передаёт конфигурации провайдеров дочернему модулю. Подробнее см. на странице providers. Если этот аргумент не указан, дочерний модуль наследует все конфигурации провайдеров по умолчанию (без псевдонимов) вызывающего модуля.

• depends_on — создаёт явные зависимости между всем модулем и указанными целями. Подробнее см. на странице depends_on.

OpenTofu не использует аргумент lifecycle. Однако блок lifecycle зарезервирован для будущих версий.

Доступ к выходным значениям модуля​

Ресурсы, определённые в модуле, инкапсулированы, поэтому вызывающий модуль не может напрямую обращаться к их атрибутам. Однако дочерний модуль может объявлять выходные значения, чтобы выборочно экспортировать определённые значения, к которым сможет обращаться вызывающий модуль.

Например, если модуль ./app-cluster, указанный в приведённом выше примере, экспортирует выходное значение с именем instance_ids, вызывающий модуль сможет обратиться к нему с помощью выражения module.servers.instance_ids:

resource "aws_elb" "example" {
  # ...

  instances = module.servers.instance_ids
}

Дополнительные сведения о ссылках на именованные значения см. в разделе Выражения.

Перенос состояния ресурсов в модули​

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

Чтобы сохранить существующие объекты, можно использовать блоки рефакторинга, записывающие старые и новые адреса каждого экземпляра ресурса. Благодаря этому OpenTofu будет считать, что существующие объекты по старым адресам изначально были созданы по соответствующим новым адресам.

Замена ресурсов в модуле​

Иногда объект нужно заменить новым по причине, которую OpenTofu не может определить автоматически, например если определённая виртуальная машина работает на неисправном оборудовании. В этом случае можно использовать параметр планирования -replace=..., чтобы указать OpenTofu предложить заменить этот объект.

Если объект относится к ресурсу во вложенном модуле, укажите полный путь к этому ресурсу, включая все ведущие к нему уровни вложенных модулей. Например:

$ tofu plan -replace=module.example.aws_instance.example

Приведённая выше команда выбирает resource "aws_instance" "example", объявленный во вложенном дочернем модуле module "example", который объявлен в корневом модуле.

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