infrastructure-terraform

Infrastructure Terraform

使用 Terraform 进行基础设施即代码的专业知识，重点关注声明式 HCL、状态管理和弹性基础设施。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 tfc-* 同级技能……
在本地编写或修改 Terraform HCL 配置	通过 API 检查 Terraform Cloud 运行状态（tfc-run-status）
针对后端运行 terraform init/plan/apply/destroy	读取 TFC 计划/应用日志流（tfc-run-logs）
设计模块结构、提供程序或远程后端	分析 TFC 运行生成的结构化计划 JSON（tfc-plan-json）
调试本地状态、漂移或导入工作流	列出或筛选 TFC 运行历史（tfc-list-runs、tfc-workspace-runs）

核心专业知识

Terraform 与 IaC

• 声明式基础设施：清晰、模块化且可复用的 HCL 代码
• 状态管理：通过远程后端保护和管理 Terraform 状态
• 提供程序与模块：利用社区和自定义提供程序/模块
• 执行生命周期：掌握 plan -> review -> apply 工作流

基础设施配置流程

1. 先制定计划：始终生成 terraform plan，并在变更前仔细审查
2. 模块化：将基础设施拆分为可复用、可组合的模块
3. 保护状态：使用带锁定功能的远程后端保护状态文件
4. 参数化：使用变量和输出，让基础设施灵活且可配置
5. 谨慎销毁：运行 terraform destroy 前仔细检查计划

必备命令

# Core workflow
terraform init                   # Initialize working directory
terraform plan                   # Generate execution plan
terraform apply                  # Apply changes
terraform destroy               # Destroy infrastructure

# State management
terraform state list            # List all resources
terraform state show <resource> # Show specific resource
terraform state pull > backup.tfstate  # Backup state

# Validation and formatting
terraform validate              # Validate configuration
terraform fmt -recursive        # Format all files recursively
terraform fmt path/to/dir       # Format specific directory
terraform graph | dot -Tsvg > graph.svg  # Dependency graph

# Working with directories (use -chdir to stay in repo root)
terraform -chdir=gcp fmt        # Format files in gcp/ directory
terraform -chdir=gcp validate   # Validate gcp/ configuration
terraform -chdir=gcp plan       # Plan from specific directory
terraform -chdir=modules/vpc init  # Init module directory

# Debugging
export TF_LOG=DEBUG             # Enable debug logging
terraform plan -out=tfplan      # Save plan for review
terraform show tfplan           # View saved plan

最佳实践

模块结构

module "vpc" {
  source  = "./modules/vpc"
  version = "1.0.0"

  vpc_cidr = var.vpc_cidr
  environment = var.environment
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

变量配置

variable "environment" {
  description = "Environment name"
  type        = string
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

远程状态后端

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

提供程序配置

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

关键调试技巧

状态调试

# State inspection
terraform state list
terraform state show aws_instance.web

# State recovery
terraform refresh
terraform plan -refresh-only
terraform import aws_instance.existing i-1234567890

错误解决

# Provider errors
terraform init -upgrade
terraform init -reconfigure

# Resource conflicts
terraform taint aws_instance.broken
terraform apply -target=aws_instance.web

Agent 优化

上下文	命令
格式化目录	terraform -chdir=path/to/dir fmt
检查格式（CI）	terraform fmt -check -recursive
验证配置	terraform -chdir=path/to/dir validate
精简计划	terraform plan -compact-warnings
JSON 计划输出	terraform plan -out=plan.tfplan && terraform show -json plan.tfplan
列出资源	terraform state list

快速参考

标志	描述
-chdir=DIR	运行命令前切换到 DIR
-recursive	递归处理目录
-check	检查格式但不进行更改（CI）
-compact-warnings	以精简形式显示警告
-json	以 JSON 格式输出
-out=FILE	将计划保存到文件
-target=RESOURCE	指定目标资源
-refresh-only	仅刷新状态，不进行更改

有关详细的调试模式、高级模块设计、CI/CD 集成和故障排除策略，请参阅 REFERENCE.md。