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

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

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

Удаление модуля​

Как и любой resource, module также можно удалить с помощью блока рефакторинга removed. Если удалить конфигурацию модуля, OpenTofu уничтожит все ресурсы, которыми управлял удалённый модуль.

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

1. Удалите модуль из конфигурации.
2. Вместо него добавьте блок removed, указав в атрибуте from адрес модуля, который нужно «забыть».
3. Укажите lifecycle.destroy = false

removed {
  from = module.some_module
  lifecycle {
    destroy = false
  }
}