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

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

Файлы .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 предоставляет множество инструментов для написания автоматизированных тестов модуля.