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

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

В каждой конфигурации 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=..., чтобы заставить 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
  }
}