Структура модуля
Тема дорожной карты · Terraform
Структура модуля Terraform — это стандартная компоновка файлов внутри директории модуля Terraform или OpenTofu, делающая его читаемым, поддерживаемым и совместимым с Terraform Registry и инструментами tflint и terraform-docs. Рекомендуемая структура модуля Terraform разделяет ответственности минимум по трём файлам: main.tf (определения ресурсов и вызовы субмодулей), variables.tf (все блоки variable) и outputs.tf (все блоки output), с необязательными дополнениями: versions.tf (фиксация required_providers и минимальной версии Terraform), locals.tf (сложные блоки locals) и README.md, генерируемым через terraform-docs. Хорошо структурированный модуль не содержит бизнес-логики в terraform.tfvars (паттерн только для корневых модулей), избегает хардкода AWS account ID, Azure subscription ID или GCP project number в блоках ресурсов и использует variable-дефолты и locals для единообразного формирования имён и тегов. Для модулей с несколькими группами ресурсов или окружениями поддиректория modules/ с узкоспециализированными субмодулями (например, modules/networking/, modules/compute/) позволяет родительскому модулю компоновать их, сохраняя каждый субмодуль независимо тестируемым через Terratest. Единообразная структура модулей Terraform в кодовой базе IaC организации ускоряет онбординг новых инженеров, обеспечивает автоматический линтинг через tflint в GitHub Actions или GitLab CI и гарантирует предсказуемое поведение terraform init и terraform plan для всех модулей.
Как это работает
Структура модуля инкапсулируют переиспользуемые инфра-паттерны. Модуль — это просто директория с *.tf; root-модуль зовёт child-модули module "name" { source = "./path" или "tfregistry/..." или "git::..." }. Входы — variable-блоки; выходы — output-блоки. Публичные модули — на Terraform Registry (registry.terraform.io); приватные — в git, S3, приватном registry. Пинните версии модулей (version = "1.2.3" или git-тег).
Когда применять
Модули — для любого инфра-паттерна, построенного больше одного раза ("сервис с ALB + ASG + RDS"). Публичные модули с Registry — для известных паттернов (VPC, k8s-кластер); экономят недели. Модули маленькие и сфокусированные; "один большой модуль на всё" хуже плоского root-конфига. Всегда версионируйте модули git-тегами + semver.
Типичные ошибки
Ловушки Структура модуля: глубоко вложенные цепочки модулей (root → A → B → C → D) — отладка боль, terraform graph помогает; модули с 30+ входными переменными (переинжинирен — разделите или примите разумные дефолты); модуль без поддержки (читайте его issues + commits перед принятием); не запиннена версия (source = "..../tags/main" сломается случайно).