Terraform 基础设施即代码

IaC 主流程（skill-flow-block）

  [ 锁定：terraform / provider / 模块 source 版本 ]
                    │
                    ▼
         [ 变量：类型约束、敏感标记、.tfvars / CI 密钥注入 ]
                    │
                    ▼
    [ fmt → validate →（可选 tflint）→ plan -out=tfplan ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
  [ 人类或策略：审 plan 摘要、标 destroy/replace ]     [ 合并阻塞项：未批准不改状态 ]
           │                 │
           └────────┬────────┘
                    ▼
         [ apply 限定：指定 plan 文件 / 受控环境 / 回滚说明 ]

状态：远程后端、锁与漂移

• 远程后端：在 SKILL 中写清 bucket / table / workspace 前缀或等价资源名规则；禁止多人共用会互相覆盖的本地 terraform.tfstate 作为事实来源。
• 状态锁：说明 CI 与本地并发时的锁超时、失败重试与「谁可 force-unlock」的审批；Agent 不应默认建议强制解锁而不经人工确认。
• 漂移：约定周期或发布前的 plan 无变更基线；发现非 Terraform 管理侧修改时，记录是 import、刷新还是人工对齐。
• 危险操作：state rm、state mv、替换 provider 或后端迁移须附检查清单与回滚路径。

远程 backend 配置（S3 + DynamoDB 锁）与变量类型约束示例：

# backend.tf — S3 远程状态 + DynamoDB 分布式锁
terraform {
  required_version = ">= 1.6.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"   # 锁定大版本，小版本可升级
    }
  }

  backend "s3" {
    bucket         = "mycompany-terraform-state"
    key            = "services/myapp/production/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "mycompany-terraform-locks"  # 防并发写

    # 角色假设（OIDC + role）替代长期 key
    role_arn = "arn:aws:iam::123456789012:role/TerraformStateRole"
  }
}

# variables.tf — 类型约束与 validation block
variable "environment" {
  type        = string
  description = "部署目标环境（dev/staging/production）"

  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "environment 必须是 dev、staging 或 production 之一。"
  }
}

variable "instance_count" {
  type        = number
  description = "EC2 实例数量（1-20）"
  default     = 1

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    error_message = "instance_count 必须在 1 到 20 之间。"
  }
}

variable "allowed_cidr_blocks" {
  type        = list(string)
  description = "允许访问的 CIDR 列表"
  default     = []

  validation {
    condition = alltrue([
      for cidr in var.allowed_cidr_blocks :
      can(cidrhost(cidr, 0))
    ])
    error_message = "allowed_cidr_blocks 中的每个值必须是合法的 CIDR 格式。"
  }
}

模块：接口、版本与重构

• 接口：在 variables.tf / outputs.tf 用描述字段文档化必填项、默认值与破坏性变更；跨团队模块建议发布语义化版本或固定 Git ref。
• 组合：根模块编排环境差异（dev/stage/prod）时，优先目录或 workspace 策略二选一并写死，避免同一套 root 隐式混用。
• 重构：使用 moved、import 块减少无意义 destroy/create；大范围重命名在 PR 中附 state 迁移或分步计划。
• 关键资源：对数据库、证书、生产入口等使用 lifecycle { prevent_destroy = true } 等护栏时，在 SKILL 中列出例外审批流程。

Terraform module 完整示例（inputs / outputs / main.tf）：

# modules/ec2-service/variables.tf
variable "service_name" {
  type        = string
  description = "服务名称，用于资源命名前缀"
}

variable "environment" {
  type        = string
  description = "部署环境（dev/staging/production）"
}

variable "instance_type" {
  type        = string
  description = "EC2 实例类型"
  default     = "t3.micro"
}

variable "subnet_ids" {
  type        = list(string)
  description = "部署的子网 ID 列表（至少 2 个可用区）"
}

# modules/ec2-service/main.tf
resource "aws_security_group" "this" {
  name        = "${var.service_name}-${var.environment}"
  description = "Security group for ${var.service_name}"

  lifecycle {
    create_before_destroy = true   # 先创新 SG，再删旧的，保证零停机
  }

  tags = {
    Name        = "${var.service_name}-${var.environment}"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

resource "aws_instance" "this" {
  ami           = data.aws_ami.al2023.id
  instance_type = var.instance_type
  subnet_id     = var.subnet_ids[0]

  vpc_security_group_ids = [aws_security_group.this.id]

  lifecycle {
    prevent_destroy = true   # 生产关键资源护栏；例外审批流程见 runbook
    ignore_changes  = [ami]  # AMI 更新由重建流程管理，不在 plan 中体现
  }
}

# modules/ec2-service/outputs.tf
output "instance_id" {
  description = "EC2 实例 ID"
  value       = aws_instance.this.id
}

output "security_group_id" {
  description = "安全组 ID，供上层模块引用"
  value       = aws_security_group.this.id
  sensitive   = false
}

# 根模块调用示例（environments/production/main.tf）
# module "web_service" {
#   source = "../../modules/ec2-service"
#   # 版本控制：固定 Git ref 或发布 tag
#   # source = "git::https://github.com/myorg/tf-modules.git//ec2-service?ref=v1.2.0"
#
#   service_name  = "web"
#   environment   = "production"
#   instance_type = "t3.medium"
#   subnet_ids    = module.vpc.private_subnet_ids
# }

流水线：fmt / validate / plan

• 顺序建议：terraform fmt -check → terraform validate →（可选）tflint / tfsec → 非交互 plan（只读凭证或 mock）。
• PR 工件：保存 plan 文本摘要或结构化输出，便于审查机器人与人类对齐「变更条数 / destroy 计数」。
• 敏感输出：对含密钥的 plan 使用 CI 密文区或脱敏展示；禁止将完整 state 或明文 secret 贴进评论。

Terraform plan 的 CI 集成与 infracost 成本估算：

# .github/workflows/terraform.yml
jobs:
  plan:
    runs-on: ubuntu-24.04
    permissions:
      id-token: write
      contents: read
      pull-requests: write   # 用于评论 plan 摘要
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.7.0"

      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.TF_PLAN_ROLE_ARN }}   # 只读角色
          aws-region: us-east-1

      - name: Terraform fmt check
        run: terraform fmt -check -recursive

      - name: Terraform validate
        run: terraform validate

      - name: tflint
        uses: terraform-linters/setup-tflint@v4
        with:
          tflint_version: v0.50.0
      - run: tflint --recursive

      - name: Terraform plan
        id: plan
        run: |
          terraform plan \
            -out=tfplan \
            -no-color \
            -input=false \
            2>&1 | tee plan.txt
          # 提取摘要：变更数与 destroy 数
          echo "summary=$(grep -E 'Plan:|No changes' plan.txt | tail -1)" >> "$GITHUB_OUTPUT"

      - name: Infracost cost estimate
        uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}
      - run: |
          infracost breakdown --path tfplan --format json > infracost.json
          infracost comment github \
            --path infracost.json \
            --github-token ${{ secrets.GITHUB_TOKEN }} \
            --pull-request ${{ github.event.pull_request.number }} \
            --behavior update

      - name: Comment plan on PR
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          message: |
            ### Terraform Plan Summary
            ${{ steps.plan.outputs.summary }}
            <details><summary>Full plan</summary>

            \`\`\`
            ${{ steps.plan.outputs.stdout }}
            \`\`\`
            </details>

Workspace 与资源地址校验

左侧输入 workspace 名（常用字母、数字、-、_）或 资源地址（如 module.vpc.aws_subnet.private[0]）。解析在浏览器本地完成，不上传。