Terraform / IaC（深度工作流）

Terraform 的核心挑战在于 状态（state）、模块（modules）、依赖关系（dependencies） 和 团队协作流程（team workflow）。应引导用户采用 可评审的执行计划（reviewable plans）、最小影响范围（least blast radius），以及确保错误具备 可恢复性（recoverable）。

何时提供该工作流

触发条件：

• 全新基础设施即代码（Greenfield IaC）、模块抽取、Provider 升级
• 发生 配置漂移（drift）、apply 失败、state 锁定问题，或误删了错误环境
• 集成 CI 实现 PR 时自动 plan、策略即代码（Policy-as-Code，如 Sentinel/OPA）

初始建议：

采用 六个阶段：（1）范围界定与结构设计，（2）模块与接口定义，（3）状态管理与 workspace 配置，（4）密钥管理与 Provider 配置，（5）plan/apply 流程与 CI 集成，（6）日常运维与漂移治理。需首先确认所用 云平台（cloud(s)） 及 远程状态后端（remote state backend）。

阶段 1：范围界定与结构设计

目标： 代码仓库布局（repo layout） 应与团队权责划分及影响范围（blast radius）对齐。

常见模式

• 单体仓库（monorepo） 与按环境拆分的 多仓库（multi-repo） —— 权衡点在于协同效率与环境隔离性
• live 目录与 modules 目录分离；环境（environment） 的组合逻辑置于项目根目录

命名规范与标签

• 统一的 资源命名规则；强制使用 标签（tags）（如 owner、env、cost center）

退出条件： 提供目录结构图；明确说明哪些资源共用同一状态，哪些需独立状态，并给出合理依据。

阶段 2：模块与接口设计

目标： 构建 可复用（reusable） 模块，具备 清晰的输入/输出定义——而非简单复制粘贴加变量替换。

实践要点

• 模块应 职责单一、体积精简；优先通过 组合（composition） 而非构建巨型模块
• 变量（variables） 需含校验块（validation blocks）；合理默认值 需在文档中明确说明
• 输出（outputs） 仅暴露消费者必需内容，避免泄露模块内部实现细节

版本管理

• 模块发布至 模块注册中心（module registry） 或通过 Git 引用（git refs） 固定版本；重大变更须维护 变更日志（changelog）

交付契约： 每个模块需提供 README，包含模块用途说明、输入参数表格及使用示例片段。

阶段 3：状态管理与 Workspace 配置

目标： 每个影响范围（blast-radius boundary）对应 唯一状态文件；杜绝因 共享状态（shared state） 导致的意外事故。

远程状态（Remote State）

• 启用 状态锁定（locking）（如 DynamoDB 或原生后端支持）；状态文件须启用 静态加密（encryption at rest）
• 状态存储桶（state bucket）的 IAM 权限需遵循 最小权限原则——注意：状态中可能包含密钥信息

Workspace vs 目录方案

• 仅当多个环境真正对称时，才考虑使用 workspace 管理并行环境；多数团队倾向采用 独立目录 + 独立状态 以提升可读性与可控性

资源导入与迁移

• 重构时优先使用 Terraform 1.x 的 moved 块；存量资源接入推荐使用 import；所有操作均需 谨慎规划（plan carefully）

退出条件： 明确记录各状态文件的 归属权（ownership）；明确标注谁有权在生产环境执行 apply。

阶段 4：密钥管理与 Provider 配置

目标： .tf 文件中不得硬编码密钥；尽可能采用 动态密钥（dynamic secrets） 方案。

实践要点

• 使用 Vault/AWS/GCP 等 Provider 获取密钥；CI 场景下优先采用 OIDC 身份认证，而非长期有效的静态密钥
• Provider 版本必须显式固定；需关注 并发数（parallelism） 对 API 速率限制的影响

退出条件： 提供密钥 流转路径图（flow diagram）；常规运维中密钥 轮转（rotation） 不应要求人工修改 TF 文件。

阶段 5：Plan / Apply 流程与 CI 集成

目标： 先 plan 再 apply；生产环境变更须经 同行评审（peer review）。

CI 实践

• PR 时自动执行 terraform fmt、validate 与 plan；可选启用 策略检查（policy checks）
• 将 plan 输出作为 构建产物（artifact） 或直接以 评论（comment） 形式展示；apply 操作仅允许从受保护分支或指定 pipeline 触发

安全机制

• 对关键资源酌情启用 prevent_destroy 属性
• 必要时可使用 target 参数 进行精准变更——但若形成习惯则属 高危操作

退出条件： 基础设施变更的 完成定义（Definition of done） 中，必须包含已评审通过的 plan。

阶段 6：日常运维与漂移治理

目标： 能够 主动发现 控制台手工变更；并能 安全地同步回代码（reconcile）。

漂移检测（Drift）

• 通过自动化任务定期执行 plan；对已确认的手工变更，有意识地通过 import 或 revert 同步至代码

紧急绕过机制（Break-glass）

• 明确文档化允许控制台操作的场景，并规定如何将变更 反向合并（backport） 至代码库

状态恢复（State Recovery）

• 若后端支持，应启用 状态备份（backups）；制定 状态文件损坏应对预案（playbook）——严禁盲目编辑状态文件

最终审查清单

• 模块边界划分与版本管理策略清晰明确
• 远程状态配置、锁定机制及 IAM 权限均已文档化
• 密钥未提交至版本控制系统（VCS），Provider 版本已固定
• CI 中 plan/apply 的治理流程已明确定义
• 漂移检测机制与恢复手段已充分理解并验证

高效指导建议

• 强调 状态即真相（state is truth）——代码必须与状态严格一致，否则将长期承担技术债务。
• 警示：count/for_each 的变更 可能引发资源销毁重建，应审慎使用 moved 与 lifecycle 块。
• 多云场景下：可抽象通用模式，但 切勿掩盖 各 Provider 特有的“陷阱（footguns）”。

应对偏离标准的情况

• Terragrunt / Pulumi：将上述六个阶段映射至其等效概念——如 stack、state、modules。
• 纯 Kubernetes 场景：需明确区分 集群本身（cluster） 的 IaC 与 集群内资源（in-cluster）（如 Helm）的管理边界。