4.16 IaC 进阶——Pulumi / CDKTF / Terragrunt 实战

预计阅读时间：16 分钟

4.15：Terraform 入门 介绍了 Terraform 的基础用法。当基础设施规模增长、多环境管理变复杂、团队对编程语言有更高诉求时，Terraform 原生的 HCL 可能不够灵活。本文覆盖四种进阶方案：Pulumi（Python/Go 替代 HCL）、CDKTF（CDK + Terraform 生态）、Terragrunt（多环境 DRY 管理）和 Terraform Cloud/Enterprise（远程执行与协作）。

学习目标

学完本章后，你将能够：

• 用 Pulumi 以 Python/Go 等通用编程语言编写 IaC，并管理 Stack 的导出值与状态
• 用 CDKTF 结合 TypeScript 与 Terraform Provider 生态定义基础设施
• 用 Terragrunt 的根级配置、dependency 与 mock_outputs 实现多环境 DRY 管理
• 配置 Terraform Cloud 远程 Backend、State 锁与 Sentinel 策略
• 对比 Pulumi / CDKTF / Terragrunt / Terraform Cloud 的适用场景并制定选型决策

前置知识

• 4.15：Terraform 入门 Terraform 入门——HCL 语法、Provider 与 State 管理基础
• 4.14：运维故障案例集 运维故障案例集——基础设施变更引发的故障复盘经验
• finops01 FinOps-1：云成本优化——多云资源成本权衡意识
• 4.1：Ansible 自动化 Ansible 自动化——基础设施自动化配置管理思维

1. Pulumi——用通用编程语言写 IaC

Pulumi 支持 Python、TypeScript、Go、C# 和 Java 等通用编程语言定义基础设施，可利用循环、条件、函数组合和 IDE 智能提示。

# 安装
curl -fsSL https://get.pulumi.com | sh

# 初始化 Python 项目（AWS）
mkdir pulumi-demo && cd pulumi-demo
pulumi new aws-python

Python 示例——EC2 + Security Group

import pulumi
from pulumi_aws import ec2

sg = ec2.SecurityGroup("web-sg",
    description="Allow HTTP and SSH",
    ingress=[
        ec2.SecurityGroupIngressArgs(protocol="tcp", from_port=80, to_port=80, cidr_blocks=["0.0.0.0/0"]),
        ec2.SecurityGroupIngressArgs(protocol="tcp", from_port=22, to_port=22, cidr_blocks=["10.0.0.0/8"]),
    ],
    egress=[ec2.SecurityGroupEgressArgs(protocol="-1", from_port=0, to_port=0, cidr_blocks=["0.0.0.0/0"])]
)

# AMI 别硬编码：用 SSM 参数按区域查询最新 Ubuntu 24.04 镜像（示例 id 已退役）：
# aws ssm get-parameter --name /aws/service/canonical/ubuntu/server/24.04/stable/current/amd64/hvm/ebs-gp3/ami-id --query Parameter.Value --output text
server = ec2.Instance("web-server",
    instance_type="t3.micro", ami="<上一步查询到的 ami-id>",
    vpc_security_group_ids=[sg.id], tags={"Name": "web-server"}
)

pulumi.export("public_ip", server.public_ip)

Go 示例——循环生成多环境 S3 Bucket

package main

import (
    "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/s3"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        // 通用语言的循环能力——HCL 中需要 count 或复制粘贴
        for _, env := range []string{"dev", "staging", "prod"} {
            _, err := s3.NewBucket(ctx, env+"-assets", &s3.BucketArgs{
                Bucket: pulumi.String("myapp-" + env + "-assets"),
                Tags:   pulumi.StringMap{"env": pulumi.String(env)},
            })
            if err != nil {
                return err
            }
        }
        ctx.Export("bucketCount", pulumi.Int(3))
        return nil
    })
}

状态后端与 Stack 管理

# Pulumi 状态可存于 Pulumi Cloud、S3、Azure Blob 或本地
pulumi login s3://pulumi-state-bucket     # S3 后端（类似 Terraform 的 s3 backend）
pulumi login azureblob://pulumi-state     # Azure Blob 后端
pulumi login --local                      # 仅本地实验使用，禁止生产

# Stack 即「同名项目 + 不同状态 + 不同配置」的组合
pulumi stack init dev                     # 创建 stack（类似 terraform workspace）
pulumi stack select prod
pulumi stack ls

# 查看导出值与配置（密钥在 state 中加密存储）
pulumi stack output public_ip
pulumi config set aws:region ap-northeast-1
pulumi config set --secret db_password    # 交互式输入，绝不写进代码

Import 已有资源

# 手工创建的存量资源可以用 pulumi import 接管（类似 terraform import）
pulumi import aws:ec2/instance:Instance web-server i-0a1b2c3d4e5f67890

# import 生成的资源定义会追加到 __main__.py，确认无误后执行
pulumi up

# 状态管理常用命令
pulumi state list          # 列出当前 state 中的全部资源
pulumi state unprotect web-server   # 解除保护后可删除该资源
pulumi refresh --target aws:ec2/instance:Instance   # 按资源刷新漂移

与 Terraform 的核心区别

2. CDKTF——AWS CDK + Terraform 生态

CDKTF（Cloud Development Kit for Terraform）让开发者用 TypeScript/Python/Go 编写 IaC，生成 Terraform 配置并复用 Terraform Provider 生态。

# 安装与初始化
npm install -g cdktf-cli
cdktf init --template=typescript
cdktf get --force  # 生成 Provider bindings

TypeScript 示例——VPC + EC2

import { App, TerraformStack } from "cdktf";
import { Construct } from "constructs";
import { AwsProvider } from "./providers/aws";
import { Vpc } from "@cdktf/provider-aws/lib/vpc";
import { Instance } from "@cdktf/provider-aws/lib/instance";

class MyStack extends TerraformStack {
    constructor(scope: Construct, id: string) {
        super(scope, id);
        new AwsProvider(this, "aws", { region: "ap-northeast-1" });
        const vpc = new Vpc(this, "vpc", { cidrBlock: "10.0.0.0/16" });
        new Instance(this, "web", {
            ami: "ami-0c55b159cbfafe1f0", instanceType: "t3.micro"
        });
    }
}
new MyStack(new App(), "cdktf-demo");

与 Terraform Provider 的关系

CDKTF 本身不直接调用云厂商 API，而是通过 cdktf get 把 Terraform Provider 的 schema 编译成对应的语言绑定（bindings）。因此：① Provider 生态完全复用 Terraform Registry；② 每次升级 Provider 版本后必须重新执行 cdktf get，否则新资源类型不会出现在语言层类型提示中；③ 语言层与执行层之间存在「生成 → 转换」的间接层。

# cdktf.json——声明 Provider 来源与后端
{
  "language": "typescript",
  "app": "npx ts-node main.ts",
  "projectId": "demo",
  "terraformProviders": ["aws@~>5.0"],
  "terraformModules": [],
  "context": { "excludeStackIdFromLogicalIds": "true" }
}

# 本地调试流程：代码 → 生成 Terraform JSON → 交给 Terraform 执行
cdktf synth          # 生成 cdktf.out/ 下的 Terraform JSON 配置
cdktf diff           # 等价于 terraform plan
cdktf deploy         # 等价于 terraform apply
cdktf destroy

# 远程后端同样支持（与 Terraform 共用同一套 backend 配置）
# 在 cdktf.json 或每个 stack 的 synth 配置中声明 s3 backend 即可，
# state 与纯 Terraform 项目完全互通

CDKTF vs Pulumi

3. Terragrunt——多环境 DRY 管理

Terragrunt 是 Terraform 的包装器，解决多环境、多模块场景下的 State 管理和配置复用问题。核心原则是 DRY。

典型目录结构

infrastructure/
├── terragrunt.hcl           # 根级公共配置
├── dev/
│   ├── env.hcl              # dev 环境变量
│   ├── vpc/terragrunt.hcl
│   ├── ecs/terragrunt.hcl
│   └── rds/terragrunt.hcl
├── staging/
│   ├── env.hcl
│   └── ...
└── prod/
    ├── env.hcl
    └── ...

根级配置与模块依赖

# infrastructure/terragrunt.hcl
remote_state {
  backend = "s3"
  generate = { path = "backend.tf", if_exists = "overwrite_terragrunt" }
  config = {
    bucket         = "my-terraform-state-${local.env}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-locks"
  }
}

# infrastructure/dev/ecs/terragrunt.hcl
include "root" { path = find_in_parent_folders() }
terraform { source = "../../modules//ecs" }

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

inputs = {
  env        = local.env
  vpc_id     = dependency.vpc.outputs.vpc_id
  subnet_ids = dependency.vpc.outputs.private_subnet_ids
}

# 常用命令
terragrunt apply                          # 单模块执行
cd infrastructure/dev && terragrunt run-all apply  # 按依赖顺序执行全部
terragrunt run-all plan                   # 批量预览
terragrunt run-all destroy                # 批量销毁

环境变量分层与依赖管理

# infrastructure/terragrunt.hcl（根级）——locals 为子目录提供公共默认值
locals {
  region = "ap-northeast-1"
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"
  default_tags {
    tags = { managed_by = "terragrunt" }
  }
}
EOF
}

# infrastructure/dev/env.hcl——环境专用变量（新增环境 = 新增目录 + 此文件）
locals {
  env      = "dev"
  region   = "ap-northeast-1"
  vpc_cidr = "10.10.0.0/16"
  ec2_type = "t3.medium"
}

# infrastructure/dev/ecs/terragrunt.hcl——子模块消费环境变量
locals {
  env_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))
  env      = local.env_vars.locals.env
}

include "root" { path = find_in_parent_folders() }
terraform { source = "../../modules//ecs" }

dependency "vpc" {
  config_path = "../vpc"
  mock_outputs = {
    vpc_id             = "vpc-00000000"
    private_subnet_ids = ["subnet-00000000"]
  }
}

inputs = {
  env           = local.env
  vpc_id        = dependency.vpc.outputs.vpc_id
  subnet_ids    = dependency.vpc.outputs.private_subnet_ids
  instance_type = local.env_vars.locals.ec2_type
}

4. Terraform Cloud / Enterprise

Terraform Cloud 提供远程执行、State 锁定、团队协作和策略即代码能力。

核心功能对比

远程 Backend 配置

terraform {
  cloud {
    organization = "my-org"
    workspaces { name = "prod-vpc" }
  }
}

Sentinel 策略示例

# 限制 EC2 实例类型必须是 t3 系列
import "tfplan/v2" as tfplan

ec2_instances = filter tfplan.resource_changes as _, rc {
    rc.type is "aws_instance" and (rc.change.actions contains "create")
}

main = rule {
    all ec2_instances as _, inst { inst.change.after.instance_type matches "t3\\..*" }
}

5. 选型对比与适用场景

选型决策流程

1. 已有 Terraform？ 配远程 backend + State 锁（Terraform Cloud 或 S3 + DynamoDB）
2. 多环境复杂？ 引入 Terragrunt 抽取公共配置
3. HCL 表达力不足？ 选 Pulumi 或 CDKTF（已有 Terraform 生态优先 CDKTF）
4. 需要合规审计？ Terraform Cloud Enterprise 或 Sentinel / OPA
5. 预算有限？ Atlantis 替代 Terraform Cloud，Terragrunt 替代 Enterprise 的 DRY 能力

6. 三框架核心差异对比

选型经验：纯运维团队（不写代码）从 Terragrunt 开始；有开发背景且需要强逻辑（批量生成、动态查询）选 Pulumi；已有 Terraform 代码库又想升级到编程语言时选 CDKTF——它不破坏现有 state。

7. 迁移路径：从 Terraform 到 Terragrunt 目录重构

存量 Terraform 仓库迁移到 Terragrunt 不需要改模块代码，只重构目录与 backend 声明：

# 迁移前——每个环境复制一份完整配置，改一个参数要改三处
terraform/
├── dev/
│   ├── main.tf          # 与 staging 完全相同的模块引用
│   ├── backend.tf       # bucket 名不同
│   └── terraform.tfvars
├── staging/
│   ├── main.tf          # 复制粘贴
│   └── ...
└── prod/
    ├── main.tf
    └── ...

# 迁移后——模块只保留一份，环境目录只放差异
terraform/
├── modules/
│   ├── vpc/
│   └── ecs/
├── terragrunt.hcl       # 根级：backend + provider + 公共 locals
├── dev/
│   ├── env.hcl          # 环境差异（cidr、实例规格、副本数）
│   ├── vpc/terragrunt.hcl
│   └── ecs/terragrunt.hcl
├── staging/...
└── prod/...

1. 第一步：抽取模块——把各环境 main.tf 里相同的资源定义抽到 modules/，子目录用 terraform.source 引用。
2. 第二步：建立根级 terragrunt.hcl——把 backend.tf 的 S3 配置迁入 remote_state 块，各环境自动生成 backend.tf。
3. 第三步：接管 state——每个模块目录执行 terragrunt init -reconfigure，state key 与旧 backend 保持一致即可无缝接管，无需 terraform state mv。
4. 第四步：验证依赖——terragrunt run-all plan 全量预览，确认依赖图输出与手工执行顺序一致后再 apply。

Pulumi 与 Terraform 代码量对比

以下对比创建相同 AWS 基础设施（VPC + 2 个子网 + EC2 实例）的代码行数：

渐进式采用路径

阶段 1：评估期（1-2 周）
├─ 在现有 Terraform 项目中引入 Terragrunt 做 DRY 管理
├─ 保持现有 .tf 文件不变，仅重构目录结构
└─ 验证 terragrunt run-all plan 输出与原始 terraform plan 一致

阶段 2：试点期（1 个月）
├─ 选一个非生产模块（如 VPC）迁移到 Terragrunt 管理
├─ 团队学习 Terragrunt 语法和工作流
└─ 积累踩坑经验，建立内部文档

阶段 3：推广期（2-3 个月）
├─ 逐步将所有环境迁移到 Terragrunt
├─ 建立模块库，标准化新模块的目录结构
└─ 配置 CI/CD 流水线自动执行 terragrunt plan/apply

阶段 4：评估 Pulumi/CDKTF（可选）
├─ 对需要复杂逻辑的模块评估 Pulumi/CDKTF
├─ 选 1-2 个模块做 POC
└─ 团队投票决定是否迁移

常见错误补充

State 管理安全检查清单

常见错误

最佳实践

• State 远程存储 + 锁定：生产环境必须使用远程 backend（S3 + DynamoDB / Terraform Cloud），禁止本地 state 文件。启用 State 锁防止并发修改导致数据丢失。
• 模块版本固定：引用 Terraform 模块或 Pulumi 包时锁定版本号，避免上游变更导致基础设施漂移。定期用 terraform init -upgrade 评估升级影响。
• 环境隔离：每个环境使用独立的 state 文件和变量文件（terraform.tfvars / Terragrunt 的 env.hcl）。生产环境的 state bucket 与开发环境分离并限制访问权限。
• Secret 不入代码库：敏感变量（数据库密码、API Key）使用 Vault、AWS SSM Parameter Store 或 Pulumi 的 pulumi.Config().requireSecret() 注入，绝不硬编码在 .tf 或 __main__.py 中。
• 渐进式采用：已有 Terraform 代码库的团队不必整体迁移。可先引入 Terragrunt 做 DRY 管理，再评估 Pulumi/CDKTF 是否值得部分模块迁移，保持新旧共存。

故障排查案例：Terragrunt 循环依赖

现象：执行 terragrunt run-all plan 报错 Circular dependency detected: vpc → ecs → vpc。

排查：检查各模块的 dependency 块，发现 vpc 模块中引用了 ecs 模块的输出（用于注入安全组规则），而 ecs 模块又依赖 vpc 的输出。

根因：vpc 模块不应该引用下游模块的输出。安全组规则的配置应放在 ecs 模块中，而非 vpc 模块。

修复：① 将安全组规则从 vpc 模块移出到独立的 security-group 模块；② 调整依赖拓扑为 vpc → security-group → ecs；③ 使用 mock_outputs 在 vpc 模块中引用安全组的输出时提供占位值。

Terragrunt 常用调试命令

# 查看依赖拓扑（确认是否有循环）
terragrunt graph-dependencies

# 只预览单个模块（不触发依赖执行）
cd infrastructure/dev/vpc && terragrunt plan

# 强制重新初始化 backend
terragrunt init -reconfigure

# 查看当前状态中的资源
terragrunt state list

# 批量执行但跳过依赖检查（紧急修复用）
terragrunt run-all apply --terragrunt-ignore-external-dependencies

练习题

1. 多环境 Terragrunt 项目：搭建一个包含 dev / staging / prod 三个环境的 Terragrunt 项目，每个环境有独立的 VPC 和 RDS 模块。要求：使用根级 terragrunt.hcl 统一配置 S3 backend 和 Provider 版本，通过 env.hcl 注入环境变量，用 dependency 块串联 VPC → RDS 的依赖关系。
2. Pulumi 组件封装：用 Pulumi（Python）封装一个可复用的 WebServer 组件，支持传入 instance_type、ami、subnet_id、security_group_ids 参数，返回实例 ID 和公网 IP。编写测试验证该组件在 dev 和 prod 环境下创建的资源属性不同。
3. Sentinel 策略编写：为 Terraform Cloud 编写两条 Sentinel 策略：① 禁止创建 ami- 开头的 EC2 实例（要求使用固定 AMI ID）；② 要求所有 S3 Bucket 必须启用服务端加密（sse_configuration）。用 sentinel test 命令验证策略的通过与失败场景。

本章总结

当 HCL 无法满足规模与协作需求时，Pulumi 与 CDKTF 让 IaC 回归通用编程语言，Terragrunt 用 DRY 结构消除多环境重复，Terraform Cloud 提供远程执行与策略门禁。四者互补而非互斥，渐进式引入——先 Terragrunt 管理多环境，再按需评估 Pulumi / CDKTF 迁移部分模块——是最稳妥的演进路径。

延伸阅读