用途
本技能用于掌握 Terraform 模块设计，创建可复用、可测试、文档完善的基础设施组件。学习何时进行模块化、模块结构模式、输入/输出设计以及组合策略。
何时使用
适用场景：
- 创建可复用基础设施模式：为重复出现的资源组构建模块
- 封装复杂配置：简化多资源配置
- 跨项目标准化：确保基础设施一致性
- 组织代码以便维护：结构化大型 Terraform 项目
- 构建可组合系统：组合模块以创建更大架构
- 版本化基础设施组件：发布并版本化模块
不适用场景：
- 单个一次性资源
- 仅使用一次的资源
- 各次使用之间无变化
触发短语：
- "Create reusable Terraform module"
- "Design module structure"
- "Define module inputs and outputs"
- "Compose multiple modules"
- "Version Terraform module"
主要能力
模块结构
标准模块布局：
modules/pubsub-topic/
├── main.tf # 资源
├── variables.tf # 输入变量
├── outputs.tf # 输出值
├── versions.tf # Provider 要求
└── README.md # 文档
根模块（主配置）：
terraform/
├── main.tf # Provider、变量
├── iam.tf # IAM 资源
├── pubsub.tf # Pub/Sub 资源
├── modules/ # 本地模块
│ └── pubsub-topic/
├── .terraform.lock.hcl
└── terraform.tfvars
模块路径支持本地模块、GitHub 远程模块和 Terraform Registry。
输入设计（变量）
原则：保持输入简单直观、使用描述性名称、提供合理默认值、验证约束。
支持简单输入、带默认值、列表、映射（配置对象）和灵活对象等模式。变量可包含 validation 块进行约束验证。
输出设计
原则：仅导出必要值、使用描述性名称、为每个输出编写文档、标记敏感输出。
模块组合
将多个模块组合以构建更大系统，可将一个模块的输出作为另一个模块的输入，并导出组合输出。
版本与维护
使用语义化版本（MAJOR.MINOR.PATCH），支持 ~> 1.0、>= 1.0, < 2.0 等版本约束。维护清单包括：定期更新 Provider 版本、使用新 Terraform 版本测试模块、记录所有破坏性变更、提供迁移指南。
使用方式
快速开始：创建可复用 Pub/Sub 模块
- 创建模块结构：
mkdir -p modules/pubsub-topic
cd modules/pubsub-topic
-
创建 main.tf、variables.tf、outputs.tf 文件（包含 topic、subscription、DLQ 资源及变量输出定义）。
-
使用模块：
module "incoming_charges" {
source = "./modules/pubsub-topic"
topic_name = "supplier-charges-incoming"
retention_days = 7
labels = {
environment = "production"
}
}
- 部署：
terraform init
terraform apply
实施步骤
-
决定何时创建模块：模式重复多次、封装复杂资源组（5+ 相关资源）、具有可配置输入、产生清晰输出时创建；单个一次性资源、仅使用一次、无变化、过度设计时不创建。
-
理解模块结构。
-
设计模块输入（变量），包含验证约束。
-
设计模块输出，标记敏感输出。
-
创建模块文档（README.md），包含 Usage、Arguments、Outputs 等部分。
-
组合模块，将输出作为其他模块输入。
-
版本与维护模块。
适用场景
- 重复出现的基础设施模式（如 Pub/Sub topic + subscription + DLQ + IAM）
- 需要跨项目标准化的资源配置
- 大型 Terraform 项目的代码组织
- 需要发布和版本化的基础设施组件
- 使用 for_each 动态创建多个模块实例
限制
- 不适用于单个一次性资源或仅使用一次的资源
- 不适用于各次使用之间无变化的场景
- 不适用于过度设计简单配置
- 要求 Terraform 1.x+
- 模块应具有清晰的输入/输出契约
- 需要良好的 README 文档
- 需使用典型用例进行测试