Refactor Module

hashicorp/agent-skills/plugins/terraform/skills/refactor-module

作者 hashicorpf706481af9b8无许可证890 个星标收录于 2026年10月8日更新于 2026年10月8日仓库4天前更新

Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

仅含说明Software DevelopmentDevOps & Cloud
AI 生成的概览

指导将单体 Terraform 配置重构为可复用、易维护的模块，并包含迁移与测试。

功能
该技能指导智能体分析现有的 Terraform 配置，并将其重构为可复用模块，包含明确的变量与输出契约、封装、文档和版本管理。它会产出模块设计、重构前后的代码转换、使用 moved 块或 terraform state mv 的状态迁移方案、模块文档以及 Terraform 测试文件。内容还涵盖重构模式、常见陷阱，以及重构后计划无差异等成功标准。
适用场景
当 Terraform 代码库已变得臃肿、需要拆分为模块时使用；也适用于将重复的资源模式抽取为可复用组件。它还适合规划状态迁移，以避免现有资源被重新创建。
运行要求
仅为说明性内容，不附带脚本。需要已有 Terraform 配置、可用的 Terraform CLI（用于 terraform state list、terraform show -json、terraform plan、terraform state mv 等命令）、通过 terraform init 安装提供程序，以及了解模块注册表模式。

Skill: Refactor Module

Overview

This skill guides AI agents in transforming monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

Capability Statement

The agent will analyze existing Terraform code and systematically refactor it into well-structured modules with:

  • Clear interface contracts (variables and outputs)
  • Proper encapsulation and abstraction
  • Versioning and documentation
  • Testing frameworks
  • Migration path for existing state

Prerequisites

  • Existing Terraform configuration to refactor
  • Understanding of resource dependencies
  • Access to inspect current state via terraform state list / terraform show -json (for migration planning)
  • Knowledge of module registry patterns

Input Parameters

ParameterTypeRequiredDescription
source_directorystringYesPath to existing Terraform configuration
module_namestringYesName for the new module
abstraction_levelstringNo"simple", "intermediate", "advanced" (default: intermediate)
preserve_statebooleanYesWhether to maintain state compatibility
target_registrystringNoTarget module registry (local, private, public)

Execution Steps

1. Analysis Phase

markdown
**Identify Refactoring Candidates**- Group resources by logical function- Identify repeated patterns- Map resource dependencies- Detect configuration coupling- Analyze variable usage patterns
**Complexity Assessment**- Count resource relationships- Measure variable propagation depth- Identify cross-resource references- Evaluate state migration complexity

2. Module Design

Interface Design
hcl
# Define clear input contractvariable "network_config" {  description = "Network configuration parameters"  type = object({    cidr_block         = string    availability_zones = list(string)    enable_nat         = bool  })
  validation {    condition     = can(cidrhost(var.network_config.cidr_block, 0))    error_message = "CIDR block must be valid IPv4 CIDR."  }}
# Define output contractoutput "vpc_id" {  description = "ID of the created VPC"  value       = aws_vpc.main.id}
output "private_subnet_ids" {  description = "List of private subnet IDs"  value       = { for k, v in aws_subnet.private : k => v.id }}
Encapsulation Strategy
markdown
**What to Include in Module:**- Tightly coupled resources (VPC + subnets)- Resources with shared lifecycle- Configuration with clear boundaries
**What to Keep Separate:**- Cross-cutting concerns (monitoring, tagging)- Resources with different lifecycles- Provider-specific configurations

3. Code Transformation

Before: Monolithic Configuration
hcl
# main.tf (monolithic)resource "aws_vpc" "main" {  cidr_block = "10.0.0.0/16"  enable_dns_hostnames = true
  tags = {    Name = "production-vpc"    Environment = "prod"  }}
resource "aws_subnet" "public_1" {  vpc_id            = aws_vpc.main.id  cidr_block        = "10.0.1.0/24"  availability_zone = "us-east-1a"
  tags = {    Name = "public-subnet-1"    Type = "public"  }}
resource "aws_subnet" "public_2" {  vpc_id            = aws_vpc.main.id  cidr_block        = "10.0.2.0/24"  availability_zone = "us-east-1b"
  tags = {    Name = "public-subnet-2"    Type = "public"  }}
resource "aws_internet_gateway" "main" {  vpc_id = aws_vpc.main.id
  tags = {    Name = "production-igw"  }}
# ... more repetitive subnet and routing resources
After: Modular Structure
hcl
# modules/vpc/main.tflocals {  subnet_count = length(var.availability_zones)}
resource "aws_vpc" "main" {  cidr_block           = var.cidr_block  enable_dns_hostnames = var.enable_dns_hostnames  enable_dns_support   = var.enable_dns_support
  tags = merge(    var.tags,    {      Name = var.name    }  )}
resource "aws_subnet" "public" {  for_each = var.create_public_subnets ? toset(var.availability_zones) : []
  vpc_id                  = aws_vpc.main.id  cidr_block              = cidrsubnet(var.cidr_block, 8, index(var.availability_zones, each.value))  availability_zone       = each.value  map_public_ip_on_launch = true
  tags = merge(    var.tags,    {      Name = "${var.name}-public-${each.value}"      Type = "public"    }  )}
resource "aws_internet_gateway" "main" {  count  = var.create_public_subnets ? 1 : 0  vpc_id = aws_vpc.main.id
  tags = merge(    var.tags,    {      Name = "${var.name}-igw"    }  )}
# modules/vpc/variables.tfvariable "name" {  description = "Name prefix for all resources"  type        = string}
variable "cidr_block" {  description = "CIDR block for the VPC"  type        = string
  validation {    condition     = can(cidrhost(var.cidr_block, 0))    error_message = "Must be a valid IPv4 CIDR block."  }}
variable "availability_zones" {  description = "List of availability zones"  type        = list(string)}
variable "create_public_subnets" {  description = "Whether to create public subnets"  type        = bool  default     = true}
variable "enable_dns_hostnames" {  description = "Enable DNS hostnames in the VPC"  type        = bool  default     = true}
variable "enable_dns_support" {  description = "Enable DNS support in the VPC"  type        = bool  default     = true}
variable "tags" {  description = "Tags to apply to all resources"  type        = map(string)  default     = {}}
# modules/vpc/outputs.tfoutput "vpc_id" {  description = "ID of the VPC"  value       = aws_vpc.main.id}
output "vpc_cidr_block" {  description = "CIDR block of the VPC"  value       = aws_vpc.main.cidr_block}
output "public_subnet_ids" {  description = "Map of availability zones to public subnet IDs"  value       = { for k, v in aws_subnet.public : k => v.id }}
output "internet_gateway_id" {  description = "ID of the internet gateway"  value       = try(aws_internet_gateway.main[0].id, null)}
# Root configuration using modulemodule "vpc" {  source = "./modules/vpc"
  name               = "production"  cidr_block         = "10.0.0.0/16"  availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
  tags = {    Environment = "production"    ManagedBy   = "Terraform"  }}

4. State Migration

Inspecting Current State

Before writing moved blocks or state mv commands, inspect the current state to map existing resource addresses. Prefer the documented, stable, and more token-efficient commands over reading the raw state file:

bash
# Enumerate current resource addresses (the inputs for `moved` / `state mv`)terraform state list
# Inspect resolved attribute values when you need themterraform show -json | jq '.values.root_module'

terraform show -json requires providers to be installed (terraform init), since it renders values against provider schemas. Fall back to the raw state (terraform state pull / terraform.tfstate) only when providers aren't available and init can't run, you need only coarse info (addresses, outputs, serial/lineage), or you must avoid executing Terraform. Avoid parsing the raw version-4 state format as a stable interface. Note: state contains sensitive values in plaintext in every format — never echo state contents into logs or output.

Generate Migration Plan
hcl
# migration.tf# Use moved blocks for state refactoring (Terraform 1.1+)
moved {  from = aws_vpc.main  to   = module.vpc.aws_vpc.main}
moved {  from = aws_subnet.public_1  to   = module.vpc.aws_subnet.public["us-east-1a"]}
moved {  from = aws_subnet.public_2  to   = module.vpc.aws_subnet.public["us-east-1b"]}
moved {  from = aws_internet_gateway.main  to   = module.vpc.aws_internet_gateway.main[0]}
Manual State Migration (Pre-1.1)
bash
# Generate state migration commandsterraform state mv aws_vpc.main module.vpc.aws_vpc.mainterraform state mv aws_subnet.public_1 'module.vpc.aws_subnet.public["us-east-1a"]'terraform state mv aws_subnet.public_2 'module.vpc.aws_subnet.public["us-east-1b"]'terraform state mv aws_internet_gateway.main 'module.vpc.aws_internet_gateway.main[0]'

5. Module Documentation

markdown
# VPC Module
## OverviewCreates a VPC with configurable public and private subnets across multiple availability zones.
## Features- Multi-AZ subnet deployment- Optional NAT gateway configuration- VPC Flow Logs integration- Customizable CIDR allocation
## Usage
\`\`\`hclmodule "vpc" {  source = "./modules/vpc"
  name               = "my-vpc"  cidr_block         = "10.0.0.0/16"  availability_zones = ["us-east-1a", "us-east-1b"]
  create_public_subnets  = true  create_private_subnets = true  enable_nat_gateway     = true
  tags = {    Environment = "production"  }}\`\`\`
## Requirements
| Name | Version ||------|---------|| terraform | >= 1.5.0 || aws | ~> 5.0 |
## Inputs
| Name | Description | Type | Default | Required ||------|-------------|------|---------|----------|| name | Name prefix for resources | `string` | n/a | yes || cidr_block | VPC CIDR block | `string` | n/a | yes || availability_zones | List of AZs | `list(string)` | n/a | yes |
## Outputs
| Name | Description ||------|-------------|| vpc_id | VPC identifier || public_subnet_ids | Map of public subnet IDs || private_subnet_ids | Map of private subnet IDs |
## Examples
See [examples/](./examples/) directory for complete usage examples.

6. Testing

Use skill terraform-test

Test File: A .tftest.hcl or .tftest.json file containing test configuration and run blocks that validate your Terraform configuration.

Test Block: Optional configuration block that defines test-wide settings (available since Terraform 1.6.0).

Run Block: Defines a single test scenario with optional variables, provider configurations, and assertions. Each test file requires at least one run block.

Assert Block: Contains conditions that must evaluate to true for the test to pass. Failed assertions cause the test to fail.

Mock Provider: Simulates provider behavior without creating real infrastructure (available since Terraform 1.7.0).

Test Modes: Tests run in apply mode (default, creates real infrastructure) or plan mode (validates logic without creating resources).

File Structure

Terraform test files use the .tftest.hcl or .tftest.json extension and are typically organized in a tests/ directory. Use clear naming conventions to distinguish between unit tests (plan mode) and integration tests (apply mode):

my-module/├── main.tf├── variables.tf├── outputs.tf└── tests/    ├── unit_test.tftest.hcl      # Unit test (plan mode)    └── integration_test.tftest.hcl  # Integration test (apply mode - creates real resources)

Refactoring Patterns

Pattern 1: Resource Grouping

Extract related resources into cohesive modules:

  • Networking (VPC, Subnets, Route Tables)
  • Compute (ASG, Launch Templates, Load Balancers)
  • Data (RDS, ElastiCache, S3)

Pattern 2: Configuration Layering

hcl
# Base module with defaultsmodule "vpc_base" {  source = "./modules/vpc-base"  # Minimal required inputs}
# Environment-specific wrappermodule "vpc_prod" {  source = "./modules/vpc-production"  # Inherits from base, adds prod-specific config}

Pattern 3: Composition

hcl
# Small, focused modulesmodule "vpc" {  source = "./modules/vpc"}
module "security_groups" {  source = "./modules/security-groups"  vpc_id = module.vpc.vpc_id}
module "application" {  source     = "./modules/application"  vpc_id     = module.vpc.vpc_id  subnet_ids = module.vpc.private_subnet_ids  sg_ids     = module.security_groups.app_sg_ids}

Common Pitfalls

1. Over-Abstraction

hcl
# ❌ Don't create overly generic modulesvariable "resources" {  type = map(map(any))  # Too flexible, hard to validate}
# ✅ Do use specific, typed interfacesvariable "database_config" {  type = object({    engine         = string    instance_class = string  })}

2. Tight Coupling

hcl
# ❌ Don't couple modules through direct references# module Aoutput "instance_id" { value = aws_instance.app.id }
# module B (in same config)resource "aws_eip" "app" {  instance = module.a.instance_id  # Tight coupling}
# ✅ Do pass dependencies through root modulemodule "compute" {  source = "./modules/compute"}
resource "aws_eip" "app" {  instance = module.compute.instance_id}

3. State Migration Errors

Always test migration in non-production first:

bash
# Create plan to verify no changes after migrationterraform plan -out=migration.tfplan
# Review carefullyterraform show migration.tfplan
# Apply only if plan shows no changesterraform apply migration.tfplan

Version Control Strategy

hcl
# Use semantic versioning for modulesmodule "vpc" {  source  = "git::https://github.com/org/terraform-modules.git//vpc?ref=v1.2.0"  version = "~> 1.2"}
# Pin to specific versions in production# Use version ranges in development

Success Criteria

  • Module has single, well-defined responsibility
  • All variables have descriptions and types
  • Validation rules prevent invalid configurations
  • Outputs provide sufficient information for consumers
  • Documentation includes usage examples
  • Tests verify module behavior
  • State migration completed without resource recreation
  • No plan differences after refactoring

Related Skills

Resources

Revision History

VersionDateChanges
1.0.02025-11-07Initial skill definition

来源与署名

来源：hashicorp/agent-skills位于plugins/terraform/skills/refactor-module提交f706481

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 hashicorp/agent-skills 的技能

Terraform Test

hashicorp

指导编写和运行 Terraform 测试，涵盖 .tftest.hcl 文件、run 块、断言、mock 与 CI 集成。

Software Development8904天前更新

Terraform Style Guide

hashicorp

按照 HashiCorp 官方风格约定和最佳实践生成并审查 Terraform HCL 代码。

DevOps & Cloud8904天前更新

Terraform Stacks

hashicorp

指导编写和验证 HashiCorp Terraform Stacks 配置文件，用于多环境基础设施。

DevOps & Cloud8904天前更新

Terraform Policy

hashicorp

编写、测试和转换 Terraform Policy 文件（.policy.hcl、.policytest.hcl）以及 Sentinel 策略。

Software Development8904天前更新

Provider Resources

hashicorp

Implement Terraform Provider resources and data sources using the Plugin Framework: CRUD operations, schema design, plan modifiers and validators, not-found handling, waiters for eventually consistent APIs, import support, resource design principles, and required acceptance test coverage. Use when adding or changing a resource or data source, deciding whether an API concept should be a resource, wiring a resource to the provider's configured client, handling drift or resource-not-found, or reviewing a resource implementation before submission.

待分类8904天前更新

Provider Framework Migration

hashicorp

指导将 Terraform provider 资源从 Plugin SDKv2 迁移到 Plugin Framework，并使用混合 provider。

Software Development8904天前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新