Terragrunt 与大规模编排：DRY、依赖图与 run-all

# 每个目录都要重复一遍，只有 key 不同
terraform {
  backend "s3" {
    bucket         = "acme-tfstate"
    key            = "prod/networking/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "acme-tf-lock"
    encrypt        = true
  }
}
# 一旦有人改了 bucket 名字却漏改某个目录，就会静默写进旧桶

# 手工编排：顺序写死、失败无回滚、并发全无
cd live/prod/networking && terraform apply -auto-approve
cd ../compute && terraform apply -auto-approve
cd ../app && terraform apply -auto-approve

# root.hcl —— 放在仓库根，所有子模块继承它
locals {
  # path_relative_to_include() 返回当前模块相对根配置的路径
  rel_path   = path_relative_to_include()
  account_id = read_terragrunt_config(find_in_parent_folders("account.hcl")).locals.account_id
  region     = read_terragrunt_config(find_in_parent_folders("region.hcl")).locals.region
}

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket         = "acme-tfstate-${local.account_id}"
    key            = "${local.rel_path}/terraform.tfstate"
    region         = local.region
    dynamodb_table = "acme-tf-lock"
    encrypt        = true
  }
}

# live/prod/us-east-1/networking/terragrunt.hcl
include "root" {
  path   = find_in_parent_folders("root.hcl")
  expose = true
}

terraform {
  source = "git::ssh://git@github.com/acme/tf-modules.git//networking?ref=v2.4.0"
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${include.root.locals.region}"
  default_tags {
    tags = { ManagedBy = "terragrunt", Env = "prod" }
  }
}
EOF
}

inputs = {
  vpc_cidr = "10.20.0.0/16"
}

# live/prod/us-east-1/compute/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

dependency "networking" {
  config_path = "../networking"

  # 上游尚未 apply 时用于 plan 的占位值，只在 plan 阶段生效
  mock_outputs = {
    vpc_id             = "vpc-00000000000000000"
    private_subnet_ids = ["subnet-00000000000000001", "subnet-00000000000000002"]
  }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

dependency "database" {
  config_path = "../database"
}

inputs = {
  vpc_id      = dependency.networking.outputs.vpc_id
  subnet_ids  = dependency.networking.outputs.private_subnet_ids
  db_endpoint = dependency.database.outputs.endpoint
}

# 只约束顺序：先跑 iam，再跑本模块，但不引用其输出
dependencies = ["../iam", "../kms"]

# 坑：mock_outputs 字段名与上游真实输出不一致时
# 现象是 plan 全绿、apply 才报 attribute not found

live/
├── root.hcl                  # 全局：backend、provider、通用 tags
├── prod/
│   ├── account.hcl           # locals { account_id = "111122223333" }
│   ├── us-east-1/
│   │   ├── region.hcl        # locals { region = "us-east-1" }
│   │   ├── networking/terragrunt.hcl
│   │   ├── database/terragrunt.hcl
│   │   └── compute/terragrunt.hcl
│   └── eu-west-1/
│       ├── region.hcl
│       └── networking/terragrunt.hcl
└── staging/
    ├── account.hcl
    └── us-east-1/
        └── networking/terragrunt.hcl

# prod/account.hcl —— 账号层的公共变量
locals {
  account_id      = "111122223333"
  account_name    = "prod"
  assume_role_arn = "arn:aws:iam::111122223333:role/TerraformDeploy"
}

# root.hcl 片段：按目录自动切换部署角色
locals {
  account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl"))
}

iam_role = local.account_vars.locals.assume_role_arn

# 预览整个环境所有模块的变更
terragrunt run-all plan

# 按依赖序执行，并发 8
terragrunt run-all apply --terragrunt-parallelism 8

# 只对某个模块及其下游生效
terragrunt run-all plan --terragrunt-include-dir "networking"

# 排除某个目录
terragrunt run-all apply --terragrunt-exclude-dir "sandbox"

# 忽略依赖错误继续跑（谨慎使用，只适合清理类操作）
terragrunt run-all destroy --terragrunt-ignore-dependency-errors

# 只跑依赖链上的模块，跳过无关目录
terragrunt run-all plan --terragrunt-strict-include --terragrunt-include-dir "compute"

# 计算本次 PR 改动的 Terragrunt 模块目录
CHANGED=$(git diff --name-only origin/main...HEAD \
  | grep 'terragrunt.hcl$' \
  | xargs -n1 dirname \
  | sort -u)

# 对每个变更目录生成 plan
for dir in $CHANGED; do
  echo "==> planning $dir"
  (cd "$dir" && terragrunt plan -out=tfplan -no-color \
    | tee "plan-$(echo "$dir" | tr '/' '_').txt")
done

# GitHub Actions 片段：plan 与 apply 分两个 job，产物跨 job 传递
name: terragrunt
on:
  pull_request:
  push:
    branches: [main]

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: terragrunt run-all plan -out=tfplan --terragrunt-parallelism 6
      - uses: actions/upload-artifact@v4
        with:
          name: tfplan
          path: "**/tfplan"

  apply:
    needs: plan
    if: github.ref == 'refs/heads/main'
    environment: production
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: tfplan
      - run: terragrunt run-all apply --terragrunt-parallelism 4

# 迁移第一步：source 指向本地已有模块，状态沿用原 key
terraform {
  source = "../../../modules//networking"
}

# 确认 plan 为空（即状态与代码一致）后，再逐步把 source 换成远端 tag
# terragrunt plan 输出为空 = 迁移无损，这是最关键的验证信号

# get_terragrunt_dir()        -> 当前 terragrunt.hcl 所在目录
# get_parent_terragrunt_dir() -> include 的根配置所在目录
# path_relative_to_include()  -> 当前目录相对根配置的路径（做 state key 最合适）

# 坑：include 未加 expose = true 就引用 include.root.locals 会直接报错
# 坑：用 path_relative_to_include("root") 传参后语义变为「相对名为 root 的 include」

# 打印依赖图（DOT 格式），可用 graphviz 渲染
terragrunt graph-dependencies | dot -Tsvg > deps.svg

# 报错信息形如：Cycle: live/prod/a -> live/prod/b -> live/prod/a
# 修复思路：把双向引用拆成单向，公共部分下沉到更底层的模块
# 或用 dependencies 只声明顺序、不取输出，断开数据回边