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

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

Каждая конфигурация 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.

• lifecycle — позволяет настраивать жизненный цикл модулей, как описано ниже в разделе Жизненный цикл модуля.

Жизненный цикл модуля​

Блок lifecycle внутри блока module позволяет настроить поведение OpenTofu для вызова модуля в целом, а не для отдельных ресурсов внутри модуля.

module "example" {
  # ...normal module call arguments...

  lifecycle {
    # ...lifecycle arguments...
  }
}

В настоящее время для настройки жизненного цикла вызова модуля поддерживается только один аргумент:

• enabled (bool) — определяет, будет ли OpenTofu использовать вызов модуля. Если задано значение false, содержимое модуля исключается из конфигурации, как если бы вызова не было. Если задано значение true (по умолчанию), модуль работает в обычном режиме.

  Дополнительные сведения см. в описании метааргумента enabled.

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

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

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

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

  instances = module.servers.instance_ids
}

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

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

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

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

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

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

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

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