Стандартна структура

Модулі

Terraform завжди працює в контексті єдиного кореневого модуля. Повна конфігурація Terraform складається з кореневого модуля та дерева дочірніх модулів (який включає модулі, викликані кореневим модулем, будь-які модулі, викликані цими модулями тощо).

У Terraform CLI кореневим модулем є робочий каталог, де викликається Terraform. (Ви можете використовувати параметри командного рядка, щоб вказати кореневий модуль за межами робочого каталогу, але на практиці це трапляється рідко.)

https://developer.hashicorp.com/terraform/language/modules

Стандартна структура модуля

https://developer.hashicorp.com/terraform/language/modules/develop/structure

Стандартна структура модулів - це структура файлів і каталогів, яку ми рекомендуємо для багаторазових модулів, що розповсюджуються в окремих репозиторіях. Інструментарій Terraform побудований таким чином, щоб розуміти стандартну структуру модулів і використовувати її для створення документації, індексації модулів для реєстру модулів тощо.

Стандартна структура модулів передбачає макет, задокументований нижче. Список може здатися довгим, але всі модулі є необов'язковими, окрім кореневого модуля. Більшість модулів не потребують додаткової роботи, щоб відповідати стандартній структурі.

• Кореневий модуль. Це єдиний необхідний елемент для стандартної структури модуля. Файли Terraform повинні існувати в кореневому каталозі сховища. Це має бути основною точкою входу для модуля, і очікується, що він буде мати власну думку. Для модуля Consul кореневий модуль встановлює повний кластер Consul. Однак він робить багато припущень, і ми очікуємо, що досвідчені користувачі використовуватимуть спеціальні вкладені модулі, щоб більш ретельно контролювати те, що вони хочуть.
• README. Кореневий модуль і всі вкладені модулі повинні мати файли README. Цей файл повинен мати назву README або README.md. Останнє буде розглядатися як уцінка (markdown). У файлі має бути опис модуля і того, для чого він буде використовуватися. Якщо ви хочете включити приклад того, як цей модуль може бути використаний у поєднанні з іншими ресурсами, помістіть його в каталог прикладів, наприклад, такий. Подумайте про те, щоб додати візуальну діаграму, що зображує ресурси інфраструктури, які може створювати модуль, і їх взаємозв'язок. У README не потрібно документувати вхідні та вихідні дані модуля, оскільки інструментарій автоматично генерує їх. Якщо ви посилаєтесь на файл або вбудовуєте зображення, що міститься у самому сховищі, використовуйте абсолютну URL-адресу, специфічну для конкретного коміту, щоб посилання не вказувало на неправильну версію ресурсу у майбутньому.
• LICENSE. Ліцензія, за якою доступний цей модуль. Якщо ви публікуєте модуль у відкритому доступі, багато організацій не приймуть його без чіткої ліцензії. Ми рекомендуємо завжди мати файл ліцензії, навіть якщо це не ліцензія з відкритим кодом.
• main.tf, variables.tf, outputs.tf. Це рекомендовані імена файлів для мінімального модуля, навіть якщо вони порожні. main.tf має бути основною точкою входу. У простому модулі це може бути місце, де створюються всі ресурси. Для складного модуля створення ресурсів може бути розбите на декілька файлів, але всі виклики вкладених модулів повинні бути в головному файлі. variables.tf та outputs.tf повинні містити оголошення змінних та виводів відповідно.
• Змінні та результати повинні мати опис. Всі змінні та результати повинні мати опис з одного або двох речень, які пояснюють їх призначення. Це використовується для документування.
• Вкладені модулі. Вкладені модулі повинні існувати у підкаталозі modules/. Будь-який вкладений модуль з файлом README.md вважається придатним для використання зовнішнім користувачем. Якщо README не існує, модуль вважається призначеним лише для внутрішнього використання. Ці рекомендації є суто рекомендаційними; Terraform не буде активно забороняти використання внутрішніх модулів. Вкладені модулі слід використовувати для розділення складної поведінки на декілька невеликих модулів, які досвідчені користувачі можуть ретельно вибирати. Наприклад, модуль Консул має вкладений модуль для створення Кластера, який є окремим від модуля для налаштування необхідних політик IAM. Це дозволяє користувачеві вносити власні варіанти політик IAM.

Якщо кореневий модуль містить виклики до вкладених модулів, вони повинні використовувати відносні шляхи на кшталт ./modules/consul-cluster, щоб Terraform вважав їх частиною одного сховища або пакета, а не завантажував їх знову окремо.

Якщо репозиторій або пакунок містить декілька вкладених модулів, в ідеалі вони мають бути компоновані користувачем, а не викликати безпосередньо один одного і створювати глибоко вкладені дерева модулів.

• Приклади. Приклади використання модуля повинні існувати у підкаталозі examples/ у корені сховища. Кожен приклад може мати README для пояснення мети та використання прикладу. Приклади для підмодулів також слід розміщувати у кореневому каталозі examples/.

Оскільки приклади часто копіюються до інших сховищ для кастомізації, будь-які блоки модулів повинні мати джерело за адресою, яку використовуватиме зовнішній користувач, а не за відносним шляхом.

Мінімальний рекомендований модуль, що відповідає стандартній структурі, показано нижче. Хоча кореневий модуль є єдиним обов'язковим елементом, ми рекомендуємо наведену нижче структуру як мінімальну:

 tree minimal-module/
 .
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf

Повний приклад модуля, що відповідає стандартній структурі, наведено нижче. Цей приклад включає всі необов'язкові елементи і тому є найскладнішим з усіх можливих модулів:

tree complete-module/
.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── ...
├── modules/
│   ├── nestedA/
│   │   ├── README.md
│   │   ├── variables.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   ├── nestedB/
│   ├── .../
├── examples/
│   ├── exampleA/
│   │   ├── main.tf
│   ├── exampleB/
│   ├── .../