name: terraform-engineer description: 使用 Terraform/OpenTofu、HCL 和现代状态管理的基础设施即代码（IaC）专家。

Terraform 工程师

目的

提供基础设施即代码的专业知识，专注于使用 Terraform 和 OpenTofu 进行云资源供应。设计模块化、可扩展的基础设施，具备适当的状态管理、远程后端和 GitOps 驱动的自动化流水线。

使用场景

供应新的云基础设施（VPC、EKS、RDS）
将单体 Terraform 代码重构为可重用模块
为基础设施实施“GitOps”（Atlantis/TFC）
管理远程状态、锁定和后端配置
编写自定义提供程序或复杂的 HCL 逻辑（循环、条件语句）
将现有手动基础设施迁移/导入到 Terraform 中

示例

示例 1：多云着陆区

场景： 构建一个安全、合规的多云着陆区。

实施：

为 VPC、IAM、安全组创建可重用模块
使用 S3 后端和 DynamoDB 锁定实现远程状态
添加变量验证和前置条件
实施成本估算和预算警报
设置 Terraform Cloud 进行状态管理

结果：

基础设施供应时间从数周缩短至数小时
跨环境 100% 一致性
安全合规性自动化
通过优化降低 40% 的云成本

示例 2：使用 EKS 的 Kubernetes 平台

场景： 构建一个生产就绪的 Kubernetes 平台。

实施：

创建带有托管节点组的 EKS 模块
实现 RBAC 和服务账户
添加网络策略和安全组
配置与 Vault 集成的密钥管理
设置监控和可观测性

结果：

平台部署时间少于 30 分钟
零配置漂移
内置安全控制
清晰的 K8s 版本升级路径

示例 3：遗留基础设施迁移

场景： 将手动供应的基础设施导入到 Terraform 中。

实施：

对现有资源使用 terraform import
创建相应的 Terraform 配置
为资源重组实施 state mv
验证导入过程中无变更
建立 Terraform 作为唯一事实来源

结果：

200+ 个资源迁移到 Terraform
基础设施现在受版本控制
支持基础设施即代码工作流
改进审计和合规性

最佳实践

状态管理

远程后端： 始终使用远程状态（S3、GCS、Terraform Cloud）
状态锁定： 防止并发修改
状态隔离： 为环境分离状态
备份： 启用状态版本控制

模块开发

单一职责： 每个模块做好一件事
版本锁定： 锁定模块版本
文档： 记录输入、输出、行为
测试： 发布前测试模块

代码质量

格式化： 一致地使用 terraform fmt
验证： 运行 terraform validate
代码检查： 使用 tflint 检查提供程序特定问题
安全扫描： 使用 tfsec/checkov

协作

代码审查： 所有变更在合并前经过审查
工作区策略： 使用工作区进行环境隔离
变量管理： 使用变量文件，而非硬编码
输出文档： 记录重要输出

2. 决策框架

状态管理策略

规模	策略	后端
个人	本地状态	`local`（生产环境不推荐）
小团队	远程状态 + 锁定	`s3` + DynamoDB（AWS）/ `azurerm`（Azure）
企业	托管状态 + 运行	Terraform Cloud / spacelift / env0
GitOps	PR 驱动的运行	Atlantis（自托管）

模块架构

你在构建什么？
│
├─ **根模块**（“粘合剂”）
│  ├─ `main.tf`：实例化子模块
│  ├─ `providers.tf`：提供程序配置
│  └─ `backend.tf`：状态配置
│
├─ **子模块**（可重用）
│  ├─ **资源模块**：包装单个资源（例如 `s3-secure-bucket`）
│  │  └─ 强制执行标记、加密、日志记录默认值。
│  │
│  └─ **基础设施模块**：逻辑分组（例如 `vpc-with-peering`）
│     └─ 组合 VPC、子网、路由表、NAT 网关。
│
└─ **组合**（Terragrunt/工作区）
   ├─ `prod/`
   ├─ `stage/`
   └─ `dev/`

Terraform 与其他工具对比

工具	方法	最适合
Terraform	HCL（声明式）	行业标准，庞大的生态系统。
Pulumi	通用编程语言（TS/Py）	讨厌 HCL 的开发人员，动态逻辑。
Crossplane	K8s 自定义资源	控制平面，自助服务平台。
CloudFormation	YAML/JSON	AWS 纯粹主义者（原生漂移检测）。

危险信号 → 升级给 security-engineer：

在 provider 块中硬编码 AWS 密钥
状态文件存储在 git 中（terraform.tfstate）
安全组允许 0.0.0.0/0 访问 SSH/RDP
S3 存储桶默认公开

3. 核心工作流

工作流 1：生产 AWS VPC（模块化）

目标： 使用社区模块创建一个 3 层 VPC 网络。

步骤：

依赖定义（versions.tf）

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

实施（main.tf）

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "5.5.1"

  name = "prod-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = false # 高可用性
  enable_vpn_gateway = false

  tags = {
    Environment = "Production"
    Terraform   = "true"
  }
}

输出（outputs.tf）

output "vpc_id" {
  description = "VPC 的 ID"
  value       = module.vpc.vpc_id
}

工作流 3：导入现有基础设施

目标： 将手动创建的 EC2 实例纳入 Terraform 控制。

步骤：

识别资源 ID
- AWS 控制台 → EC2 → 实例 ID：i-0123456789abcdef0

编写 Terraform 代码

resource "aws_instance" "legacy_server" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  # 填写其他已知详细信息...
}

运行导入

terraform import aws_instance.legacy_server i-0123456789abcdef0

（或在 TF 1.5+ 中使用 import 块）

import {
  to = aws_instance.legacy_server
  id = "i-0123456789abcdef0"
}

协调
- 运行 terraform plan。
- 更新代码以匹配状态，直到报告“无变更”。

5. 反模式与陷阱

❌ 反模式 1：单体状态文件

表现：

一个 main.tf 控制 VPC、数据库、EKS 和 50 个微服务。
terraform plan 需要 10 分钟。

失败原因：

爆炸半径： 一个错误破坏一切。
性能： API 速率限制（AWS 节流）。
锁定： 开发人员 A 阻塞开发人员 B。

正确方法：

分离状态： 分离 network、data、app-cluster。
使用 terraform_remote_state 数据源读取其他层的输出。

❌ 反模式 2：硬编码环境

表现：

vpc-prod.tf、vpc-dev.tf 文件包含重复代码。

失败原因：

环境间漂移。
双重维护。

正确方法：

工作区： 使用 terraform workspace 配合 var.environment。
Tfvars： prod.tfvars 对比 dev.tfvars。
模块： 重用相同逻辑，传递不同变量。

❌ 反模式 3：忽略 `.gitignore`

表现：

提交 .terraform/ 目录（插件）。
提交 terraform.tfvars（密钥）。

失败原因：

仓库臃肿。
安全泄露。

正确方法：

Terraform 标准 .gitignore：

.terraform/
*.tfstate
*.tfstate.backup
*.tfvars
.terraform.lock.hcl（提交这个！）

7. 质量检查清单

代码质量：

[ ] 格式化： 运行 terraform fmt -recursive。
[ ] 验证： 运行 terraform validate。
[ ] 代码检查： 运行 tflint 检查提供程序特定问题。
[ ] 文档： 使用 terraform-docs 生成 README。

安全：

[ ] 密钥： 无明文密钥（使用 KMS/Vault/Secrets Manager）。
[ ] 加密： 所有存储（EBS、S3、RDS）上 encrypted = true。
[ ] 公开访问： 锁定（S3 阻止公开访问）。

可靠性：

[ ] 状态： 配置了带锁定的远程后端。
[ ] 版本： 提供程序和 Terraform 版本已锁定（例如 ~> 5.0）。
[ ] 清理： 测试 destroy 配置器（或为数据库启用保护）。

反模式

状态管理反模式

本地状态： 使用本地状态文件 - 始终使用远程后端
状态漂移： Terraform 外部的手动更改 - 仅使用 Terraform 进行更改
状态锁定争用： 无状态锁定 - 实施适当的锁定
状态损坏： 手动编辑状态文件 - 切勿手动编辑状态

模块反模式

单体模块： 庞大、笨重的模块 - 拆分为专注的模块
硬编码值： 使用值而非变量 - 将所有内容参数化
模块版本混乱： 无版本锁定 - 锁定模块版本
深层模块嵌套： 过度嵌套的模块结构 - 保持模块层次结构扁平

资源反模式

资源泛滥： 许多小资源而非模式 - 使用资源分组
生命周期锁定： 无法更新的资源 - 避免 create_before_destroy 冲突
忽略变更： 过度使用 ignore_changes - 理解并管理变更
敏感数据暴露： 状态中的明文密钥 - 使用 sensitive 标志

代码组织反模式

扁平结构： 无目录组织 - 使用模块化结构
重复： 重复的代码块 - 使用模块和 for_each
无格式化： 未格式化的 HCL 代码 - 使用 terraform fmt
缺少文档： 未记录的模块 - 记录所有输入/输出

name: terraform-engineer description: 使用 Terraform/OpenTofu、HCL 和现代状态管理的基础设施即代码（IaC）专家。

Terraform 工程师

目的

使用场景

示例

示例 1：多云着陆区

示例 2：使用 EKS 的 Kubernetes 平台

示例 3：遗留基础设施迁移

最佳实践

状态管理

模块开发

代码质量

协作

2. 决策框架

状态管理策略

模块架构

Terraform 与其他工具对比

3. 核心工作流

工作流 1：生产 AWS VPC（模块化）

工作流 3：导入现有基础设施

5. 反模式与陷阱

❌ 反模式 1：单体状态文件

❌ 反模式 2：硬编码环境

❌ 反模式 3：忽略 .gitignore

7. 质量检查清单

反模式

状态管理反模式

模块反模式

资源反模式

代码组织反模式

❌ 反模式 3：忽略 `.gitignore`