writing-infrastructure-code

基础设施即代码

使用基于代码的自动化工具来配置和管理云基础设施。本技能涵盖 Terraform/OpenTofu、Pulumi 和 AWS CDK 的工具选择、状态管理、模块设计和运维模式。

适用场景

在以下情况下使用本技能：

• 配置云基础设施（计算、网络、数据库、存储）
• 从手动管理基础设施迁移到基于代码的工作流
• 设计可复用的基础设施模块
• 实施多云或混合云部署
• 建立状态管理和漂移检测模式
• 将基础设施配置集成到 CI/CD 流水线
• 评估 IaC 工具（Terraform、Pulumi 还是 CDK）

常见请求：

• “创建一个用于配置 VPC 的 Terraform 模块”
• “为团队协作设置带锁定功能的远程状态”
• “针对我们的用例比较 Pulumi 和 Terraform”
• “设计可组合的基础设施模块”
• “为现有基础设施实施漂移检测”

核心概念

基础设施即代码基础

关键原则：

1. 声明式与命令式 - 描述期望状态（Terraform）或通过编程来构建基础设施（Pulumi）
2. 幂等性 - 相同输入产生相同输出，可安全重复运行
3. 版本控制 - 在 Git 中跟踪基础设施变更
4. 状态管理 - 跟踪实际基础设施状态
5. 模块组合 - 可复用、带版本的基础设施组件

优势：

• 可复现性（相同代码 = 相同基础设施）
• 可审计性（Git 历史记录显示所有变更）
• 协作性（通过代码评审审查基础设施变更）
• 自动化（CI/CD 部署基础设施）
• 灾难恢复（通过代码重建）

工具选择框架

根据团队构成和云战略选择 IaC 工具：

Terraform/OpenTofu - 声明式，基于 HCL

• 多云和混合云部署
• 运维/SRE 团队偏好声明式方法
• 最大的提供商生态系统（AWS、GCP、Azure、3000+ 个提供商）
• 成熟的模块注册表和社区

Pulumi - 命令式，基于编程语言

• 熟悉 TypeScript/Python/Go 的开发者团队
• 复杂逻辑需要编程结构（循环、条件、函数）
• 使用熟悉的测试框架进行原生单元测试
• 强类型和 IDE 支持

AWS CDK - AWS 原生，基于编程语言

• 仅使用 AWS 的基础设施
• 与 AWS 服务紧密集成
• L1/L2/L3 构造抽象
• 底层使用 CloudFormation

决策树：

Multi-cloud required?
├─ YES → Team composition?
│  ├─ Ops/SRE focused → Terraform/OpenTofu
│  └─ Developer focused → Pulumi
└─ NO → AWS only?
   ├─ YES → Language preference?
   │  ├─ HCL/declarative → Terraform
   │  ├─ TypeScript/Python → AWS CDK
   │  └─ YAML/simple → CloudFormation
   └─ NO → GCP/Azure only?
      └─ Terraform or Pulumi

状态管理架构

带锁定功能的远程状态支持团队协作：

后端选择：

云提供商	推荐后端	锁定机制
AWS	S3 + DynamoDB	DynamoDB 表
GCP	Google Cloud Storage	原生
Azure	Azure Blob Storage	基于租约
多云	Terraform Cloud/Enterprise	内置
Pulumi	Pulumi Service	内置

状态隔离策略：

1. 目录分离（大多数团队推荐）

   • 每个环境使用单独的目录（prod/、staging/、dev/）
   • 完全隔离状态文件
   • 不存在跨环境污染的风险

2. 工作区

   • 单一代码库，多个环境
   • 共享状态后端，按环境命名空间隔离
   • 风险：意外执行跨环境操作

3. 分层架构

   • 为网络、计算和数据层使用单独的状态文件
   • 缩小影响范围
   • 通过远程状态数据源进行跨层引用

关键状态管理规则：

• 团队环境始终使用远程状态
• 启用状态文件静态加密
• 为状态存储启用版本控制
• 使用状态锁定以防止并发修改
• 切勿将状态文件提交到 Git
• 将敏感输出标记为 sensitive = true

模块设计模式

可组合的模块结构：

modules/
├── vpc/              # Network foundation
├── security-group/   # Reusable security group patterns
├── rds/              # Database with backups, encryption
├── ecs-cluster/      # Container orchestration base
├── ecs-service/      # Individual microservice
└── alb/              # Application load balancer

模块版本管理：

• 在生产环境中固定模块版本（version = "5.1.0"）
• 内部模块采用语义化版本控制
• 先在非生产环境中测试模块更新
• 为模块发布维护 CHANGELOG

模块设计原则：

• 明确的输入约定（必需变量与可选变量）
• 文档化输出（使用者可引用的内容）
• 尽可能提供合理的默认值
• 输入验证规则
• 展示用法的 examples 目录

何时创建模块：

• 资源组会重复使用 3 次或以上
• 边界和职责明确
• 接口约定稳定
• 团队有能力维护模块

何时保持单体结构：

• 一次性基础设施
• 快速原型开发阶段
• 资源之间耦合度高
• 团队规模小，基础设施简单

快速参考

Terraform/OpenTofu 命令

# Initialize providers and backend
terraform init

# Plan changes (preview)
terraform plan

# Apply changes
terraform apply

# Destroy infrastructure
terraform destroy

# Format HCL files
terraform fmt

# Validate syntax
terraform validate

# Show state
terraform state list
terraform state show <resource>

# Import existing resources
terraform import <resource.name> <id>

# Workspace management
terraform workspace list
terraform workspace new staging
terraform workspace select prod

Pulumi 命令

# Initialize new project
pulumi new aws-typescript

# Preview changes
pulumi preview

# Apply changes
pulumi up

# Destroy infrastructure
pulumi destroy

# Show stack outputs
pulumi stack output

# Manage stacks
pulumi stack ls
pulumi stack select prod

# Import existing resources
pulumi import <type> <name> <id>

# Export/import state
pulumi stack export > state.json
pulumi stack import < state.json

AWS CDK 命令

# Initialize new app
cdk init app --language typescript

# Synthesize CloudFormation
cdk synth

# Preview changes
cdk diff

# Deploy stack
cdk deploy

# Destroy stack
cdk destroy

# Bootstrap account/region
cdk bootstrap

# List stacks
cdk list

常见模式检查清单

基础设施预配：

• 已配置带锁定功能的远程状态
• 已启用状态文件加密
• 已固定提供程序版本
• 已固定模块版本（生产环境）
• 变量均包含描述和类型
• 敏感输出已标记为敏感
• 已实施标记策略
• 已应用成本分配标记

模块开发：

• README 清晰，并附有用法示例
• 已记录必需变量和可选变量
• 已附带说明记录输出
• 关键输入已设置验证规则
• examples 目录中包含可运行的代码
• 已测试模块行为（Terratest/CDK assertions）
• 已维护用于跟踪版本的 CHANGELOG
• 已遵循语义化版本控制

运维就绪：

• 已安排漂移检测
• 已为 plan/apply 配置 CI/CD 流水线
• 已制定状态备份策略
• 已记录灾难恢复流程
• 已配置团队访问控制（IAM/RBAC）
• 已集成成本估算（Infracost）
• 已集成安全扫描（Checkov/tfsec）
• 文档保持最新

详细文档

如需了解完整模式和实现细节：

特定工具的模式：

• references/terraform-patterns.md - Terraform/OpenTofu 最佳实践、HCL 模式
• references/pulumi-patterns.md - 使用 TypeScript/Python/Go 的 Pulumi

架构与设计：

• references/state-management.md - 远程状态、锁定、隔离策略
• references/module-design.md - 可组合模块、版本管理、注册表

运维：

• references/drift-detection.md - 检测并修复基础设施漂移

实用示例

展示 IaC 模式的实际实现：

Terraform 示例：

• examples/terraform/vpc-module/ - 包含公有/私有子网的多可用区 VPC
• examples/terraform/ecs-service/ - 包含 ALB 和自动扩缩的 ECS 服务
• examples/terraform/rds-cluster/ - 包含备份和加密的 Aurora 集群
• examples/terraform/state-backend/ - S3 + DynamoDB 后端配置

Pulumi 示例：

• examples/pulumi/typescript/vpc/ - TypeScript VPC 组件
• examples/pulumi/python/ecs-service/ - Python ECS 服务
• examples/pulumi/go/rds-cluster/ - Go RDS 集群
• examples/pulumi/testing/ - Pulumi 程序的单元测试

AWS CDK 示例：

• examples/cdk/typescript/vpc-stack/ - 使用 L2 构造的 VPC
• examples/cdk/typescript/ecs-fargate/ - 包含 ALB 的 Fargate 服务
• examples/cdk/typescript/pipeline-stack/ - 自变更 CDK 流水线
• examples/cdk/testing/ - CDK assertions 和快照测试

实用脚本

自动化验证和运维工具：

• scripts/validate-terraform.sh - Terraform fmt、validate、tflint
• scripts/cost-estimate.sh - 用于成本分析的 Infracost 封装脚本
• scripts/drift-check.sh - 定时漂移检测
• scripts/security-scan.sh - Checkov/tfsec 安全扫描
• scripts/state-backup.sh - 状态文件备份自动化
• scripts/module-release.sh - 模块版本管理和发布

与其他技能集成

部署流水线：

• building-ci-pipelines - 在 CI/CD 中自动执行 terraform plan/apply
• gitops-workflows - 基于 GitOps 的基础设施部署

平台工程：

• kubernetes-operations - 配置 EKS、GKE、AKS 集群
• platform-engineering - 内部开发者平台基础设施

安全：

• secret-management - 配置 Vault、External Secrets Operator
• security-hardening - 实施基础设施安全控制
• compliance-frameworks - 用于合规的策略即代码

运维：

• observability - 配置监控基础设施（Prometheus、Grafana）
• disaster-recovery - 基础设施重建流程
• cost-optimization - 通过 IaC 实施成本控制

数据平台：

• data-architecture - 配置数据湖、数据仓库
• streaming-data - 配置 Kafka、Kinesis 基础设施

最佳实践

开发工作流：

1. 在功能分支中编写基础设施代码
2. 在本地运行 terraform plan / pulumi preview
3. 提交包含 plan 输出的拉取请求
4. 代码审查侧重于安全性、成本和影响范围
5. CI 运行自动化测试和安全扫描
6. 仅在获得批准且 CI 通过后应用变更
7. 部署后监控配置漂移

状态管理：

• 从一开始就使用远程状态（团队绝不使用本地状态）
• 为每个环境单独设置状态文件
• 启用状态锁定，防止并发修改
• 对状态存储进行版本控制，以便回滚
• 对静态存储中的状态进行加密（其中包含敏感数据）
• 定期将状态备份到其他位置

模块开发：

• 从单体代码开始，在出现模式后再提取模块
• 设计时考虑可复用性，但避免过早抽象
• 记录所有输入和输出
• 在 examples/ 目录中提供可运行的示例
• 在模块中固定 provider 版本
• 发布前测试模块
• 使用语义化版本控制发布

安全：

• 应用前扫描 IaC 中的安全问题（Checkov、tfsec）
• 绝不将密钥提交到代码中（使用密钥引用）
• 将敏感输出标记为 sensitive = true
• 实施最小权限 IAM 策略
• 默认启用资源加密
• 内部模块使用私有模块注册表

成本管理：

• 应用变更前估算成本（Infracost）
• 为所有资源添加标签，以便分配成本
• 在拉取请求中审查成本影响
• 设置成本漂移警报
• 根据使用情况调整资源规格

卓越运维：

• 定期安排配置漂移检测
• 记录灾难恢复流程
• 为常见运维任务维护操作手册
• 监控状态文件访问日志
• 定期演练基础设施重建
• 在测试的同时及时更新 provider 版本

常见问题

状态文件问题：

• 手动编辑状态 - 使用 terraform state 命令，而非直接编辑
• 未启用状态锁定 - 竞态条件会破坏状态
• 团队使用本地状态 - 团队成员之间的状态会出现偏差
• 状态文件过大 - 按层拆分为多个状态文件

模块设计：

• 过度抽象 - 过于通用，难以理解
• 抽象不足 - 到处复制粘贴代码
• 未固定版本 - 可能出现意外的破坏性变更
• 没有示例 - 用户不知道如何使用模块

运维：

• 未检测配置漂移 - 手动变更不会被发现
• 直接修改资源 - 绕过 IaC 会导致配置漂移
• 没有回滚计划 - 无法从应用失败中恢复
• 忽略 plan 输出 - 应用时会遇到意外情况

安全：

• 代码中包含密钥 - 凭据被硬编码
• 未进行安全扫描 - 漏洞进入生产环境
• IAM 权限过宽 - 权限过多
• 未加密状态 - 敏感数据暴露

故障排除指南

状态锁定问题：

terraform force-unlock <lock-id>  # Use only if certain no other process running

导入现有资源：

terraform import aws_vpc.main vpc-12345678
pulumi import aws:ec2/vpc:Vpc main vpc-12345678

配置漂移检测：

terraform plan -detailed-exitcode  # Exit 2 = drift detected
pulumi preview --diff

有关配置漂移修复的详细信息，请参阅 references/drift-detection.md。

状态恢复：

# Terraform: Restore from S3 versioning
aws s3 cp s3://bucket/backup/terraform.tfstate terraform.tfstate

# Pulumi: Restore from checkpoint
pulumi stack export --version <timestamp> | pulumi stack import

相关技能

云平台专属实现：

• aws-patterns - AWS 专属资源模式
• gcp-patterns - GCP 专属资源模式
• azure-patterns - Azure 专属资源模式

基础设施运维：

• kubernetes-operations - 管理通过 IaC 配置的 Kubernetes 集群
• gitops-workflows - 基于 GitOps 的基础设施部署
• platform-engineering - 内部开发者平台

安全与合规：

• security-hardening - 基础设施安全控制
• secret-management - 密钥注入与轮换
• compliance-frameworks - 用于合规的策略即代码

部署自动化：

• building-ci-pipelines - 基础设施代码的 CI/CD
• deploying-applications - 将应用程序部署到已配置的基础设施

成本与可观测性：

• cost-optimization - 基础设施的 FinOps 实践
• observability - 监控基础设施运行状况