provision-infrastructure-terraform

Provision Infrastructure with Terraform（使用 Terraform 预置基础设施）介绍如何以基础设施即代码的方式，在 AWS、Azure、GCP 及其他提供商上预置、版本化和管理云资源。

适用场景

预置新的云基础设施（VPC、计算、存储、数据库）
从 ClickOps 或 CloudFormation 迁移到声明式 IaC
管理多环境基础设施（dev、staging、production）
在团队间实施可复现的基础设施模式
将基础设施变更与应用代码一起版本化
通过可复用模块强制实施基础设施标准

输入要求

必需：已安装 Terraform CLI（terraform --version）
必需：云提供商凭证（AWS、Azure、GCP 服务账号）
必需：远程状态后端配置（S3、Azure Storage、Terraform Cloud）
可选：需要导入或迁移的现有基础设施
可选：用于团队协作的 Terraform Cloud/Enterprise
可选：用于校验和格式化的 pre-commit 钩子

操作步骤（详见扩展示例中的完整配置文件与模板）

第 1 步：初始化 Terraform 项目结构创建包含后端配置和提供商设置的目录结构。示例通过 mkdir -p terraform/{modules,environments/{dev,staging,prod}} 建立项目结构，并创建 backend.tf，其中指定 required_version = ">= 1.6"、AWS provider 版本约束 ~> 5.0、S3 后端（bucket、key、region、encrypt、dynamodb_table、workspace_key_prefix）以及 provider 的 default_tags。随后创建 variables.tf，定义 aws_region、project_name（含长度校验）、environment（含 dev/staging/prod 枚举校验）等变量，最后运行 terraform init。预期：初始化成功、下载 provider 插件、配置远程后端，生成 .terraform/ 目录并验证状态后端连接。失败处理：后端初始化失败时检查 S3 桶是否存在及 IAM 权限（s3:GetObject、s3:PutObject、dynamodb:GetItem、dynamodb:PutItem）；provider 下载失败时检查网络与代理，可运行 terraform init -upgrade。

第 2 步：创建可复用基础设施模块为 VPC、计算和数据基础设施构建带输入校验的可组合模块。示例模块 modules/vpc 定义 vpc_cidr、availability_zones、project_name、environment 变量，使用 locals 定义 common_tags，创建 aws_vpc、公有与私有 aws_subnet（通过 cidrsubnet 与 count 分配）、aws_internet_gateway、aws_eip、aws_nat_gateway，并在 outputs.tf 中输出 vpc_id、public_subnet_ids、private_subnet_ids、nat_gateway_ips。预期：模块跨多个可用区创建 VPC、公有/私有子网、互联网网关和带 EIP 的 NAT 网关，输出供下游模块使用。失败处理：CIDR 重叠时调整 cidrsubnet() 或校验 VPC CIDR；依赖错误时检查 depends_on；可用 terraform graph | dot -Tpng > graph.png 可视化依赖。

第 3 步：实现环境特定配置创建带变量覆盖和数据源的环境工作区，例如 environments/prod/main.tf。预期：生产环境配置使用 3 个可用区、更大的实例类型和生产安全设置，数据源解析最新 AMI，模板渲染环境变量。失败处理：工作区错误时用 terraform workspace new prod 创建；数据源失败时检查 AWS 凭证是否具备 ec2:DescribeImages 权限；模板渲染错误时校验变量类型。

第 4 步：执行 plan 与 apply 工作流运行 terraform fmt -recursive 格式化、terraform validate 校验，并执行计划与应用。提供 GitHub Actions 集成示例（.github/workflows/terraform.yml），在 pull_request 时触发。预期：plan 显示资源的增删改、无漂移，apply 无错误创建/更新资源，CI 在 PR 上评论 plan 并在 main 分支合并后自动 apply。失败处理：plan 失败时运行 terraform validate 捕获语法错误；状态锁错误时用 aws dynamodb get-item 查找锁持有者并在过期时 force-unlock；apply 失败时查看 CloudWatch 日志；用 terraform show 检查当前状态。

第 5 步：管理状态并实现漂移检测配置状态锁定、备份和自动漂移检测。示例创建 aws_dynamodb_table（名为 terraform-lock，PAY_PER_REQUEST，hash_key = LockID），并创建 scripts/detect-drift.sh 脚本。预期：状态后端具备版本控制和加密，漂移检测能识别带外变更，状态操作（list、show、mv、import）无错误，自动漂移检查按计划运行并告警。失败处理：状态锁超时时检查 DynamoDB 表与键模式；版本问题用 aws s3api get-bucket-versioning 检查；导入失败时验证资源存在且配置与属性匹配。

第 6 步：实现模块测试与文档使用 Terratest 添加自动化测试并生成文档。示例包含 test/vpc_test.go（Go 语言，使用 testing 包），并通过 go install github.com/terraform-docs/terraform-docs@latest 安装 terraform-docs，运行 terraform-docs markdown table modules/vpc > modules/vpc/README.md 生成文档。预期：Terratest 验证模块创建的资源与配置，文档自动生成，pre-commit 钩子强制格式化和校验。失败处理：Terratest 失败时检查 AWS 凭证与配额，长测试可用 t.Parallel()；文档生成错误时确认所有变量都有 description；pre-commit 失败时手动运行 terraform fmt。

验证清单

后端配置了加密、版本控制和状态锁定
所有模块均有输入校验和输出值
工作区隔离环境特定状态
apply 后 terraform plan 显示无意外变更
漂移检测自动运行并在变更时告警
模块经 Terratest 或类似框架测试
文档自动生成并保持更新
密钥通过 AWS Secrets Manager 管理而非硬编码
集成成本估算（Infracost 或类似工具）
通过每环境独立状态最小化影响范围

常见陷阱

硬编码值：避免硬编码 AMI ID、可用区或账户特定值，使用数据源和变量
缺少 lifecycle 块：资源意外重建，添加 lifecycle { create_before_destroy = true } 以防更新时停机
无状态锁定：并发 apply 会损坏状态，始终配合 S3 后端使用 DynamoDB 表锁定
IAM 权限过宽：Terraform 服务账号拥有完全管理员权限，应实施最小权限策略
无版本约束：provider 更新会破坏基础设施，用 version = "~> 5.0" 固定版本
状态中的密钥：敏感值以明文存储在状态文件中，对输出使用 sensitive = true，密钥存入 AWS Secrets Manager 并通过数据源引用
无备份策略：状态文件丢失或损坏且无恢复计划，启用 S3 版本控制、定期备份并测试恢复
单体配置：单个状态文件管理全部基础设施，应按逻辑边界（网络、计算、数据）拆分以减小影响范围

技能介绍