使用 Terraform Stacks…

在创建、修改或验证 Terraform Stacks 配置（.tfcomponent.hcl、.tfdeploy.hcl）时，用于声明式编排跨环境、区域、云账号的多组件基础设施。

适用场景

解决思路

1. 在 Stack 根目录添加 .terraform-version 文件，指定 Terraform v1.13.x 或更高版本（如 1.14.5），以使用 Stacks CLI 插件和 terraform stacks 命令。
2. 按推荐结构组织文件：variables.tfcomponent.hcl、providers.tfcomponent.hcl、components.tfcomponent.hcl、outputs.tfcomponent.hcl、deployments.tfdeploy.hcl，所有配置文件放在 Stack 仓库根目录，HCP Terraform 按依赖顺序处理。
3. 在 .tfcomponent.hcl 中用 variable 块声明输入变量，必须定义 type，不支持 validation；对凭证和令牌（identity token、API key、密码）设置 ephemeral = true 防止持久化到 state，对需要跨运行持久化的值（如 license key）使用 stable。
4. 用 required_providers 块声明 provider 来源和版本（如 aws = { source = "hashicorp/aws", version = "~> 6.0" }）。
5. 用 provider 块配置 provider：支持 for_each 元参数，别名写在块头部而非参数，配置通过 config 块传入；优先使用 workload identity（OIDC）配合 identity_token 块和 assume_role_with_web_identity 进行认证，避免长期静态凭证。
6. 用 component 块为每个模块定义组件，指定 source（本地路径、公共/私有 registry 或 Git URL）、version（registry 模块）、inputs 和 providers；组件间依赖通过引用 component.<name>.<output> 自动推断，for_each 组件用 component.<name>[key].<output> 引用，可用 for 表达式聚合输出。
7. 用 output 块定义 Stack 输出，必须提供 type，不支持 preconditions；用 locals 块定义共享值（在 .tfcomponent.hcl 和 .tfdeploy.hcl 中用法相同）。
8. 用 removed 块安全移除组件，需提供该组件的 providers。
9. 在 .tfdeploy.hcl 中用 identity_token 块生成 JWT 令牌用于 OIDC 认证（如 audience = ["aws.workload.identity"]），在 deployment 中通过 identity_token.<name>.jwt 引用。
10. 用 store 块访问 HCP Terraform 变量集（指定 id 或 name、source、category 为 terraform 或 env），集中管理凭证并跨 Stack 共享。
11. 用 deployment 块定义部署实例（每个 Stack 最少 1 个、最多 20 个），为不同环境/区域/云账号提供不同 inputs；销毁部署时设置 destroy = true，上传配置、批准销毁运行后再移除 deployment 块。
12. 用 deployment_group 块将部署分组以共享设置（HCP Terraform Premium 功能；免费/标准层使用默认组 {deployment-name}_default），多个部署可引用同一组。
13. 用 deployment_auto_approve 块定义自动批准规则（Premium 功能），可用上下文变量 context.plan.applyable、context.plan.changes.add/change/remove/total、context.success；orchestrate 块已弃用，改用 deployment_group 和 deployment_auto_approve。
14. 用 publish_output 块发布一个 Stack 的输出，用 upstream_input 块（type = "stack"，source 指向 Stack 地址）在另一个 Stack 中消费，实现 Stack 间链接。
15. 使用 CLI 初始化与验证：terraform stacks init 下载 provider/模块并生成锁文件，terraform stacks providers-lock 重新生成锁文件，terraform stacks validate 检查语法。
16. 部署工作流：terraform stacks configuration upload 上传配置并自动触发部署运行（无 plan/apply 命令）；用 terraform stacks deployment-run list 列出运行，terraform stacks deployment-group watch -deployment-group=... 流式查看状态；用 terraform stacks deployment-run approve-all-plans -deployment-run-id=... 或 terraform stacks deployment-group approve-all-plans -deployment-group=... 批准计划，terraform stacks deployment-run cancel -deployment-run-id=... 取消。
17. 配置管理：terraform stacks configuration list 列出配置版本，terraform stacks configuration fetch -configuration-id=... 下载配置，terraform stacks configuration watch 监控上传状态。
18. 其他命令：terraform stacks create 交互式创建 Stack，terraform stacks fmt 格式化文件，terraform stacks list 列出所有 Stack，terraform stacks version 显示版本，terraform stacks deployment-group rerun -deployment-group=... 重跑部署。
19. 在自动化、CI/CD 或非交互环境（如 AI agent）中，改用 HCP Terraform API 而非 CLI watch 命令进行程序化监控：查询配置状态与验证、部署组摘要、部署运行状态、部署步骤详情、带文件位置和代码片段的错误诊断；用 artifacts 端点获取 Stack 输出（GET /api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-description，返回 307 重定向需用 curl -L）；诊断端点需带 stack_deployment_step_id 查询参数。
20. 遵循最佳实践：按共享生命周期划分组件粒度；Stacks 使用的模块不能包含 provider 块（provider 在 Stack 配置中配置）；生产使用前测试公共 registry 模块（部分模块如 ALB、ECS 存在兼容性问题），不确定时考虑用原始资源；每个部署有独立 state；跨部署不同的值用变量、共享值用 locals；始终生成并提交 .terraform.lock.hcl；使用描述性命名；用部署组组织部署并启用自动批准规则；在生产前于 dev/staging 部署中测试。
21. 排查常见问题：循环依赖通过重构或引入中间组件打破；部署销毁不能从 UI 操作，需设置 destroy = true 后上传配置；诊断 API 返回空时补充 stack_deployment_step_id 查询参数；模块兼容性问题在生产前测试。

适用边界 · 注意事项

• 需要依赖 HCP Terraform（含 Premium 层功能如 deployment_group、deployment_auto_approve）和 Terraform CLI v1.13+ 的场景，纯本地或非 HCP Terraform 工作流不适用。
• 模块包含 provider 块时不能直接用于 Stacks，需先改造或改用原始资源。
• 未经验证的公共 registry 模块（如部分 terraform-aws-modules 的 ALB、ECS 模块）可能不兼容，生产环境慎用。