refactor-module

refactor-module — официальный навык HashiCorp для преобразования монолитной Terraform-конфигурации в переиспользуемые модули. Его задача не сводится к механическому перемещению ресурсов по папкам: workflow требует сначала понять зависимости, границы ответственности и совместимость существующего state, а затем спроектировать интерфейс модуля и проверить результат. В качестве входа источник ожидает каталог конфигурации, имя нового модуля, желаемый уровень абстракции и явное решение о сохранении совместимости состояния; registry для результата может быть локальным, приватным или публичным. Первая фаза — анализ. Навык предлагает сгруппировать ресурсы по логической функции, найти повторяющиеся шаблоны, построить карту зависимостей, увидеть связанность конфигурации и глубину передачи переменных. Отдельно оцениваются число связей между ресурсами и сложность миграции state. Такой порядок нужен, чтобы не вынести в один модуль случайный набор ресурсов и не потерять поведение при переносе. Для инфраструктуры с долгоживущими объектами полезно заранее изучить terraform state list и terraform show -json, а не принимать структуру файлов за полную модель текущего состояния. В проектировании интерфейса источник делает акцент на явно типизированных variables и outputs. Пример VPC использует object для сетевых параметров, validation для CIDR, отдельные outputs для идентификатора VPC и подсетей, а tags передаются картой. Внутрь модуля предлагается включать тесно связанные ресурсы с общим жизненным циклом; cross-cutting concerns, provider-specific configuration и объекты с другим lifecycle лучше оставить отдельно. Это ограничивает радиус изменений и делает контракт понятным потребителю. Описанные паттерны включают группировку ресурсов, слой базового модуля с defaults и environment-specific wrapper, а также композицию небольших модулей через outputs и входы корневого модуля. Источник предупреждает о двух типичных ошибках. Слишком универсальный map(map(any)) затрудняет валидацию, поэтому предпочтительнее конкретные object-типы. Прямая связка модулей через внутренние ресурсы усиливает coupling; зависимости следует передавать через root module. Для примера VPC указаны multi-AZ subnet deployment, опциональные public/private subnets и NAT gateway, VPC Flow Logs и настраиваемый CIDR, но это свойства демонстрационного модуля, а не обещание, что каждый проект должен иметь такую архитектуру. После рефакторинга нужны документация с примером использования, описания variables и outputs, validation rules и тесты. Источник связывает этот workflow с terraform-test: тестовые файлы .tftest.hcl или .tftest.json могут проверять plan без ресурсов либо apply с инфраструктурой, а unit- и integration-сценарии стоит разделять по назначению. Для миграции состояния сначала создают plan в непроизводственной среде, сохраняют его через -out, проверяют terraform show и применяют только если не ожидается пересоздание ресурсов. Критерий успеха — один понятный scope модуля, достаточный контракт, отсутствие неожиданных plan differences и подтверждённая совместимость state. Навык не заменяет ревью конкретной Terraform-конфигурации и не гарантирует безопасную миграцию без проверки фактического state, провайдеров и окружения. В примере источника заявлены Terraform >= 1.5.0 и AWS provider ~> 5.0, однако перед применением нужно сверить версии целевого проекта. Рефакторинг следует завершать тестами, просмотром плана и ручной проверкой границ модулей; абстракцию не стоит расширять, пока повторяющийся сценарий и его контракт не подтверждены данными проекта.