Создание модулей

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

Файлы .tf и/или .tofu в рабочем каталоге при запуске tofu plan или tofu apply вместе образуют корневой модуль. Этот модуль может вызывать другие модули и связывать их, передавая выходные значения одного модуля входным значениям другого.

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

Структура модуля​

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

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

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

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

Когда следует создавать модуль​

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

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

Например, aws_instance и aws_elb — это типы ресурсов провайдера AWS. С помощью модуля можно представить более высокоуровневое понятие — кластер HashiCorp Consul, работающий в AWS, который, помимо прочего, состоит из этих ресурсов провайдера AWS.

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

Рефакторинг ресурсов модуля​

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

Основные составляющие модуля​

Чтобы модуль был хорошо документирован и готов к публикации, его авторам следует позаботиться о нескольких составляющих.

Файл Readme​

Файл README.md в корневом каталоге должен объяснять пользователям, как использовать модуль. Если лицензия это допускает, этот файл будет отображаться в поиске по реестру.

Лицензия​

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

Подмодули​

Модуль также может содержать подмодули. Чтобы подмодули отображались в поиске по реестру, поместите их в каталог modules/MODULENAME внутри каталога модуля.

В каждом каталоге подмодуля может находиться файл README.md с дополнительной информацией о назначении подмодуля.

Примеры​

Примеры, подобно подмодулям, помогают пользователям быстро начать работу с модулем. Чтобы пример появился в поиске по реестру OpenTofu, его нужно поместить в каталог examples/EXAMPLENAME и добавить файл README.md с дополнительной информацией о примере.

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

Тесты помогают убедиться, что модуль продолжает работать при поступлении запросов на включение изменений от сообщества. Команда tofu test предоставляет множество инструментов для написания автоматизированных тестов модуля.