Модуль из Terraform Registry

Шаги

1. 01

   Посмотри документацию модуля

   Подключим terraform-aws-modules/s3-bucket/aws. Это самый популярный community-модуль для S3.

   Документация: https://registry.terraform.io/modules/terraform-aws-modules/s3-bucket/aws/latest

   В реальной работе тебе нужно прочитать секции:

   • Inputs, какие переменные принимает.
   • Outputs, какие значения возвращает.
   • Examples, готовые примеры использования.
   • Provider Versions, какая версия AWS-провайдера нужна.
   • CHANGELOG.md в git-репо, что было в прошлых версиях.

   Это первое что ты делаешь перед использованием любого community-модуля. Не пишешь HCL → не дебажишь ошибки → читаешь.

   Пока ничего не делаем, просто понимаем процесс.

   ✓ Готово к подключению.

2. 02

   Подключи модуль с заморожённой версией

   Создай main.tf:

   hclcopy

   resource "random_id" "suffix" {

     byte_length = 4

   }

   module "logs_bucket" {

     source  = "terraform-aws-modules/s3-bucket/aws"

     version = "~> 4.0"

     bucket = "linuxlab-registry-logs-${random_id.suffix.hex}"

     versioning = {

       enabled = true

     }

     tags = {

       Owner   = "student"

       Project = "registry-lesson"

     }

   }

   output "registry_bucket_arn" {

     value = module.logs_bucket.s3_bucket_arn

   }

   Ключевое:

   • source, три сегмента namespace/name/provider, без https://.
   • version = "~> 4.0", pessimistic constraint, см. tf-module-versioning. Берёт любую 4.x, но не 5.x.
   • bucket, versioning, tags, input'ы модуля. Их имена и формат , из его документации, не выдуманы.
   • module.logs_bucket.s3_bucket_arn, output модуля. Опять же, имя не выдумано, берётся из секции Outputs модуля.

   ✓ Подключение описано. Теперь init.

3. 03

   init: скачать модуль и подмодули

   bashcopy

   cd /home/student/tf-registry

   terraform init

   Internet-доступ нужен только Terraform Registry, сам HCL модуля будет ходить на LocalStack endpoints, не на real AWS.

   В выводе должно быть:

   copy

   Initializing modules...

   Downloading registry.terraform.io/terraform-aws-modules/s3-bucket/aws ...

   Проверь что скачалось:

   bashcopy

   cat .terraform/modules/modules.json | jq '.Modules[] | {Key, Source, Version}'

   Увидишь основной модуль и его подмодули (большие community-модули внутри используют другие модули). Это нормально, что вызывал ты один, а в .terraform/modules/ может оказаться 5 директорий.

   подсказка

   Если init падает с network error: проверь internet: `curl -I https://registry.terraform.io`. В нашем sandbox это должно работать (links.internal: false).

   ✓ Модуль скачан. Теперь plan и apply.

4. 04

   Apply: модуль создаёт бакет

   bashcopy

   terraform apply -auto-approve

   Плагины модуля видят AWS-endpoints, настроенные в provider.tf (мы их унаследовали от aws-localstack-provider.tf). Внутри модуля никакой специальной настройки, просто aws_s3_bucket. Поэтому он работает и на LocalStack, и на real AWS.

   После apply посмотри state:

   bashcopy

   terraform state list | grep module

   Адресы внутри модуля могут выглядеть так:

   copy

   module.logs_bucket.aws_s3_bucket.this[0]

   module.logs_bucket.aws_s3_bucket_versioning.this[0]

   Заметь [0], community-модуль использует count = local.create ? 1 : 0 внутри (опциональное создание). Это типичный паттерн в больших модулях.

   ✓ Registry-модуль создал бакет внутри своей вложенности.

   То же самое на OpenTofu

   OpenTofu держит CLI и state совместимыми с Terraform по командам этого шага: миграция обычно проходит через mv .terraform .terraform.bak; tofu init -upgrade. Но при первом переходе сделай backup state и прогон на feature-branch - расхождения концентрируются в новых фичах (variables в backend, state-encryption, OCI registry-backed модули). См. tf-opentofu-parity для полной матрицы.

   • → OpenTofu parity
5. 05

   Прочитай output модуля

   bashcopy

   terraform output registry_bucket_arn

   Должен вывестись ARN бакета (arn:aws:s3:::linuxlab-registry-logs-...).

   Это значение прошло через два контракта:

   • Модуль объявил output "s3_bucket_arn" { value = ... }.
   • Root объявил output "registry_bucket_arn" { value = module.logs_bucket.s3_bucket_arn }.

   Без явного output на уровне root, наружу из root наглядно ничего не видно. Output модуля доступен только через адрес module.X.<имя>, но terraform output показывает только root-level outputs.

   ✓ Контракт замкнулся: модуль → root → CLI.

   Когда не использовать Registry-модуль

   Готовый модуль, экономия времени, но не всегда удачный выбор:

   • 90% input'ов тебе не нужны. terraform-aws-modules/vpc/aws имеет 200+ переменных. Если ты используешь 5, твой HCL выглядит обманчиво простым, но в depend-tree куча кода которого ты не знаешь. Дебаг падает.

   • Поведение «магии». Хороший community-модуль документирует поведение, но не всегда, встречаются модули с неочевидными зависимостями (например, автоматически создают IAM-роль).

   • Версии и upgrade-боль. Major-апгрейд (4.x → 5.x) обычно ломает контракт. Если у тебя 50 root'ов используют модуль, апгрейд это спринт работы.

   • Свой модуль на 100 строк vs Registry на 5000 строк. Если твои нужды простые, свой модуль лучше. Полный контроль, ясный граф зависимостей.

   Правило: community-модуль, когда экосистема за тобой. Большая AWS-инфра, ALB+EKS+RDS, берёшь community. Маленький проект, часто проще написать свой.

   • → Источники модулей
   • → Версионирование модулей