IaC 工具选型：CDKTF、Pulumi 与原生 HCL 的取舍

路线 A：声明式 HCL
  写 .tf 文件 → terraform 解析 → 资源图 → provider 调用

路线 B：编程语言 SDK（Pulumi 模式）
  写 Python/TS/Go → 语言运行时求值 → 资源对象注册 → provider 调用

路线 C：CDK 生成器（CDKTF 模式）
  写 TypeScript → 语言运行时求值 → 生成 cdk.tf.json → terraform 执行

resource "aws_s3_bucket" "logs" {
  bucket = "example-logs-prod"
}

resource "aws_s3_bucket_versioning" "logs" {
  bucket = aws_s3_bucket.logs.id

  versioning_configuration {
    status = "Enabled"
  }
}

import { S3Bucket, S3BucketVersioningA } from "@cdktf/provider-aws";

const bucket = new S3Bucket(this, "logs", { bucket: "example-logs-prod" });

new S3BucketVersioningA(this, "logs-versioning", {
  bucket: bucket.id,
  versioningConfiguration: { status: "Enabled" },
});

import { App, TerraformStack, TerraformOutput } from "cdktf";
import { AwsProvider } from "@cdktf/provider-aws/lib/provider";
import { Instance } from "@cdktf/provider-aws/lib/instance";

class WebStack extends TerraformStack {
  constructor(scope: App, id: string) {
    super(scope, id);

    new AwsProvider(this, "aws", { region: "ap-northeast-1" });

    const web = new Instance(this, "web", {
      ami: "ami-0c55b159cbfafe1f0",
      instanceType: "t3.micro",
      tags: { Name: "web", Env: "prod" },
    });

    new TerraformOutput(this, "public_ip", { value: web.publicIp });
  }
}

const app = new App();
new WebStack(app, "web-prod");
app.synth();

# 安装 provider 绑定并生成 provider 元数据
cdktf get

# 求值程序，产出 cdktf.out/stacks/web-prod/cdk.tf.json
cdktf synth

# 查看生成的配置：排查抽象层问题时最先看这个
jq '.resource' cdktf.out/stacks/web-prod/cdk.tf.json

# 计划与部署：内部调用 terraform plan / apply
cdktf plan web-prod
cdktf deploy web-prod

# 销毁与清理生成产物（生成物不入库）
cdktf destroy web-prod
rm -rf cdktf.out

import pulumi
import pulumi_aws as aws

bucket = aws.s3.Bucket(
    "logs",
    bucket="example-logs-prod",
    tags={"Env": "prod", "ManagedBy": "pulumi"},
)

# 引用 bucket.id 即建立依赖边，无需显式 depends_on
policy = aws.s3.BucketPolicy(
    "logs-policy",
    bucket=bucket.id,
    policy=bucket.arn.apply(
        lambda arn: f'{{"Effect":"Allow","Action":"s3:GetObject","Resource":"{arn}/*"}}'
    ),
)

pulumi.export("bucket_name", bucket.id)

# 登录并选择状态后端（自管：S3 或本地文件）
pulumi login s3://example-pulumi-state?region=ap-northeast-1

# 初始化项目栈并设置配置
pulumi stack init prod
pulumi config set aws:region ap-northeast-1

# 预览变更（等价于 terraform plan）
pulumi preview

# 应用变更并写入状态
pulumi up --yes

class MonitoredDatabase {
  constructor(scope: Construct, id: string, opts: DatabaseOptions) {
    const db = new DbInstance(this, id, {
      engine: "postgres",
      instanceClass: opts.size,
      backupRetentionPeriod: opts.backupDays ?? 7,
    });

    new CloudwatchMetricAlarm(this, `${id}-cpu`, {
      comparisonOperator: "GreaterThanThreshold",
      threshold: opts.cpuThreshold ?? 80,
      alarmActions: [opts.alertTopicArn],
    });

    new TerraformOutput(this, `${id}-endpoint`, { value: db.endpoint });
  }
}

// 反例：Map 遍历顺序在不同语言运行时可能不同
const envs: Record<string, string> = { prod: "t3.large", dev: "t3.micro" };
for (const [env, size] of Object.entries(envs)) {
  new Instance(this, `web-${env}`, { instanceType: size });
}

// 反例：时间戳进入资源属性 → 每次 synth 都产生 diff
new S3Bucket(this, "logs", { bucket: `logs-${Date.now()}` });

// 正例：稳定排序 + 显式版本常量，保证每次 synth 结果一致
new S3Bucket(this, "logs", { bucket: "logs-v1" });

# 反例：用动态长度数组生成资源，插入一个元素导致后续全部重建
# 资源地址形如 aws_instance.web[0]、aws_instance.web[1]……

# 正例：用稳定键生成地址，插入元素不影响既有资源
# 资源地址形如 aws_instance.web["api"]、aws_instance.web["worker"]

# CI 中的额外要求：语言运行时必须在流水线里可用
node --version      # CDKTF 需要 Node 18+
python3 --version   # Pulumi 需要 Python 3.9+
cdktf get           # 每次依赖变化都要重新生成 provider 绑定

陷阱清单
1. 隐式依赖：资源引用了计划外的外部数据源，plan 时才发现
2. 非确定性：Map 顺序、时间戳、随机后缀导致 plan 不收敛
3. 状态膨胀：动态循环地址不稳定，改动引发连锁重建
4. 运行时依赖：CI 必须装 Node/Python，镜像与缓存策略变复杂
5. 动态循环：循环次数依赖运行时数据，plan 结果无法静态预测

# 把既有 HCL 目录转换为 CDKTF 代码骨架
cdktf convert --language typescript ./legacy

# 用 cdktf import 采纳已在 state 中的资源
cdktf import aws_instance.web i-0abc123def456

# cdktf.out/ 由 CDKTF 管理，legacy/ 由手写 HCL 管理
# 二者通过相同的 terraform state 后端共享记录

分阶段替换顺序（CDKTF）
阶段 1：新资源用 CDKTF 写，旧资源保持 HCL，共享同一 state 后端
阶段 2：按模块转换，每转一个模块跑一次 plan，确认无删除
阶段 3：转换完成后移除手写 HCL，统一走 cdktf deploy
阶段 4：把 cdktf.out 加入 .gitignore，只提交源码与 lock 文件

# 逐个导入既有资源
pulumi import aws:s3/bucket:Bucket logs example-logs-prod

# 导入后立即 preview，确认无意外变更
pulumi preview

# 从 Terraform 侧移除已迁走的资源
terraform state rm aws_s3_bucket.logs

反模式 1：资源不足百级就引入语言 IaC
  → 抽象成本高于复用收益，团队只学会语法没拿到收益

反模式 2：HCL 与 Pulumi 长期并行管理同一批资源
  → 双管状态下 plan 与 preview 结论互相矛盾，事故高发

反模式 3：CI 中跳过 plan 直接 apply
  → 语言 IaC 的执行期副作用无法静态审查，跳过 plan 等于放弃唯一护栏

反模式 4：用类继承层级表达环境差异
  → 继承链越深，plan 越难预测，环境差异应显式参数化