IaC 与 GitOps：Terraform、Pulumi、Argo CD 与 drift 检测

0. 元信息

• 主题路径：docs/topics/ci-cd-and-release/subtopics/iac-and-gitops/README.md
• 主分类：工程技术
• 辅助分类：安全与可靠性
• 适合对象：已经能跑通 CI + canary，想把云资源与集群期望状态纳入版本控制的开发者
• 建议周期：5～8 天，每天 1.5～2 小时
• 前置知识：release-strategies-and-rollout
• 最终目标：能用 Terraform/Pulumi 管云资源，用 Argo CD/Flux 管集群期望状态，配 drift 检测与多环境/多云

1. 学习路线

Terraform 基础：HCL、provider、state、module
  → remote state + lock（s3 + DynamoDB / Terraform Cloud）
  → Pulumi：用通用语言写 IaC
  → Ansible：配置管理与轻量 provisioner
  → GitOps 理念：声明式期望状态、controller 收敛
  → Argo CD：Application、AppProject、Sync、Drift
  → Flux：GitRepository、Kustomize、HelmRelease
  → 多环境/多集群：ApplicationSet、cluster generator

2. 阶段周数分配

精简子主题不固定周数。按概念、正常路径、失败路径、综合实验四段推进，共 5～8 天。

3. 九阶段表

4. 第一周任务

精简子主题省略逐日表。每天只引入一个变量；先跑正常路径，再做四类失败实验。Day 1 必须明确 state 后端与 lock 机制。

5. 阶段通用验收

采用父主题 §5；本页额外要求保存 HCL、Argo CD manifest、drift 报告、清理命令与回滚路径。

6. 最终验收

完成 1 份 Terraform module（带 remote state + lock）、1 段 Argo CD Application（带 Self-Heal）、1 个 Flux GitRepository、至少 4 类失败实验（drift、state 损坏、lock 死锁、provider 版本漂移），并用 10 分钟解释期望状态与收敛。

7. 综合项目

把本页产出合入父主题首选项目：GitHub Actions → GHCR → k8s Argo Rollouts 金丝雀发布全链路。单独交付时，提供 Terraform repo、Argo CD repo、ApplicationSet、drift 演练记录、notes/retrospective.md。

本主题贡献

本主题把云资源与集群期望状态纳入 Git：Terraform / Pulumi IaC 描述期望、remote state + lock 防并发、ArgoCD / Flux GitOps controller 持续收敛、Helm chart 与 Kustomize overlay 模板化、drift 检测到 Self-Heal 自动化。

职责（3 项）

1. 用 HCL 写 Terraform module、按业务边界拆（不按资源类型），配 s3 + DynamoDB remote backend lock，能解释为什么 state 禁入 Git、为什么 ~> 5.0 锁 provider major、为什么 moved block 优于 import、为什么 Pulumi 用通用语言写 stack 区分环境；
2. 写 ArgoCD Application（destination.namespace、syncPolicy.automated.prune=true、selfHeal=true）与 AppProject（管多 Application 的 RBAC），能解释期望状态 vs 实际的差异、argocd app diff 检测 drift、kubectl edit 被 Self-Heal 覆盖；
3. 配 Flux GitRepository + Kustomization + HelmRelease 串联 Helm chart 与 Kustomize overlay，能解释 GitRepository → Kustomization → HelmRelease 依赖链、flux get kustomizations 健康判定、为什么 ApplicationSet generator 能 100 集群自动生成 Application。

交付物（4 项）

1. Terraform module（vpc / 应用各一）+ remote state backend（S3 + DynamoDB lock）+ terraform plan 输出稳定；
2. ArgoCD Application manifest（dev/stage/prod 三环境）+ Self-Heal 配置 + drift 演练记录（手动改集群后 argocd app diff 检测 → Self-Heal 收敛）；
3. Flux GitRepository + Kustomization + HelmRelease YAML，flux get kustomizations / flux get helmreleases 健康；
4. ApplicationSet（cluster generator 跨多集群）+ PR generator + cluster secret 清单，100 cluster 自动生成 Application。

指标（3 项）

1. drift 检测到收敛时长 ≤ 5 分钟（argocd app diff + Self-Heal）；
2. state lock 冲突率 = 0（并发 plan 不损坏 state，CI 串行 + lock table 监控）；
3. Self-Heal 覆盖率 ≥ 99%（手动 kubectl edit / console 改动被 controller 收敛）。

8. 推荐开源资料

Terraform（HashiCorp，MPL-2.0）作主线；Pulumi（Apache-2.0）作通用语言对照；OpenTofu（Linux Foundation，MPL-2.0）作 Terraform fork；Argo CD（CNCF，Apache-2.0）作 GitOps controller；Flux CD（CNCF，Apache-2.0）作对照；Ansible Core（GPL-3.0）作配置管理；Crossplane（Apache-2.0）作 k8s-native IaC。复制前核对当前 LICENSE。

9. 学习资料汇聚（v0.3 自包含）

9.1 背景与动机

IaC 把云资源变成可版本化、可复现、可审计的代码。Terraform 用 HCL 描述期望状态；Pulumi 用通用语言；Ansible 用 YAML 描述 task。GitOps 把同样的理念搬到 Kubernetes：期望状态在 Git，controller 持续收敛。

Argo CD 与 Flux 是事实上的 GitOps controller 标准。Weaveworks 的 Alexis Richardson 在 2017 年提出 GitOps 一词。Kubernetes 生态让 GitOps 成为可能：声明式 API + controller pattern + CRD。

这一节要解决一个具体问题：怎么把「人改 kubectl」、「人登 console」、「脚本乱改」变成「Git 是 single source of truth，controller 自动收敛」。答案靠 IaC + GitOps + drift 检测 + audit log。

9.2 概念地图

flowchart LR
  HCL[HCL / Terraform] --> State[remote state + lock]
  Pulumi[Pulumi TS/Go/Py] --> State
  Ansible[YAML / Ansible] --> State
  State --> Cloud[cloud resources]
  Git[Git repo] --> Controller[Argo CD / Flux]
  Controller --> K8s[cluster actual state]
  Controller -.drift.-> Diff[argocd app diff / flux detect]
  Diff --> Sync[re-sync / self-heal]
  Sync --> K8s
  Audit[audit log] -.反馈.-> Git

核心关系：声明式期望状态在 Git；controller 持续比较期望与实际；diff 触发 sync；IaC 管云资源；audit log 反馈到 Git。

9.3 基础知识讲解

9.3.1 论文 / 规范

9.3.2 书

9.3.3 博客 / 文档

9.3.4 人物

9.3.5 方法

9.4 经典问题与经典案例

9.5 学习难点

概念难点

思维难点

工程难点

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

Terraform / Pulumi 管云资源；Ansible 管配置；Argo CD / Flux 管集群期望状态；Helm / Kustomize 管 k8s manifest；Crossplane 把云资源暴露为 k8s CRD；External Secrets 把 secret 同步进集群。

9.6.3 Structure

Terraform：HCL（resource / data / variable / output / module / provider）。Argo CD：Application、AppProject、ApplicationSet、Cluster、Repo。Flux：GitRepository、Kustomization、HelmRelease、HelmRepository、Source。Pulumi：stack、config、output、component。Ansible：playbook、inventory、role、task、handler。

9.6.4 Ecosystem

Terraform 有 registry、Terraform Cloud、Terraform Enterprise；Pulumi 有 Pulumi Cloud；Argo CD 有 ApplicationSet、Notifications、Argo Workflows；Flux 有 Flux GitOps Toolkit。Crossplane 提供 AWS / Azure / GCP provider；External Secrets 支持 Vault / AWS SM / GCP SM / Azure KV。

9.6.5 Depth Tiers

本子主题目标是 L3。

9.6.6 Source

• Terraform 文档
• Pulumi 文档
• Argo CD 文档
• Flux 文档
• Crossplane 文档
• 引用版本快照日期：2026-07-30；实作前运行 terraform version、argocd version、flux version。

10. 常见误区

• 把 state 文件 commit 进 Git；
• provider 不锁版本；
• module 边界按资源类型拆；
• 多环境共用同一 backend；
• drift 不报警，全靠人看；
• Self-Heal 全开，没人 review；
• ApplicationSet 写了但不验证 cluster secret；
• Pulumi stack 直接用 default，不区分环境；
• Ansible playbook 用 raw command，不幂等；
• Helm chart 升级失败 rollback 没验证；
• External Secrets 没配刷新间隔，secret 长期过期；
• Terraform Cloud / Spacelift audit log 没接；
• 集群 RBAC 配太宽，Argo CD 拿到 cluster-admin；
• Argo CD 删 Application 把生产资源一起删。

11. 所有知识点分类（统一规则）

1. 编程语言；2. 数据结构与算法；3. 计算机基础；4. 工程技术；5. Web 与后端；6. 前端与客户端；7. 数据与人工智能；8. 项目与职业能力；9. 安全与可靠性。

本计划归属：工程技术 主 + 安全与可靠性 辅。