在 GCP 上用 Terraform 设计…

面向 GCP 的 Terraform 基础设施全生命周期工作流：本地设计校验、最佳实践扫描、导入 ADC 模板、部署、排障与端到端验证。

适用场景

解决思路

1. 确认目标 GCP 项目 ID 和位置（region）；若用户未指定位置，默认使用 us-central1；用 `gcloud config set project <project_id>` 设置本地活动项目。
2. 调用 `design` 技能处理用户需求：它会自动完成代码库分析、查询目录注册表、规划、生成 HCL，并在专用 scratch 目录中执行本地 CLI 校验循环（`terraform init`、`validate`、`plan`）。
3. 定位 `design` 技能保存已校验、可编译 Terraform 文件的 scratch 目录（如 `scratch/tf_validate_<session_id>/`）。
4. 强制验证交接：确认本地校验循环已成功完成且 plan 干净；检查 HCL 是否满足 Secret-Safe 策略（`terraform.tfvars` 或资源块中无明文凭据/密码/硬编码密钥，敏感输入必须通过 GCP Secret Manager 接入）和 State Isolation 策略（HCL 文件中无远程 backend 块，如 `backend "gcs" {}`，校验期间 state 保留在 scratch 目录本地，由 ADC 在导入时处理远程 state 注册）；若发现违规，在 HCL 中修正、重新本地校验并再次验证，不得用未校验或不安全的代码继续。
5. 强制导出 Terraform Plan 为 JSON：在 scratch 目录运行 `terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json`，确认 `tfplan.json` 已成功写入。
6. 强制发现 Space ID：运行 `gcloud design-center spaces list --project=<project_id> --location=<location>`，解析输出识别活动 space（如 `test-deploy` 或 `googlespace`）；若存在多个 space，请用户确认；若不存在，询问用户或运行 `gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>` 创建。
7. 通过 gcloud 执行 plan 评估：使用发现的 Space ID 和导出的 `tfplan.json` 运行 `gcloud design-center spaces generate-terraform-assessment-report <space_id> --location=<location> --project=<project_id> --terraform-plan="<scratch_directory_path>/tfplan.json" --format=json`。
8. 以清晰表格形式向用户展示所有发现，详列具体违规、资源范围和关联严重级别。
9. 本地修复循环：不要导入或提交不安全代码；在 scratch 目录编辑本地 HCL 文件修复报告的违规（如添加加密密钥、启用 OS Login、限制 IAM 范围）；重新运行 `terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json`，并重新运行 plan 评估命令。
10. 退出标准：所有高/严重发现已解决，或可接受的权衡已记录；最多进行三（3）次迭代尝试；干净或可接受后进入 Phase 3。
11. 强制验证或创建 Application Template：先运行 `gcloud design-center spaces application-templates describe <template_id> --space=<space_id> --project=<project_id> --location=<location>` 检查模板是否存在；若返回 `NOT_FOUND`，先运行 `gcloud design-center spaces application-templates create <template_id> --space=<space_id> --project=<project_id> --location=<location> --display-name="<Name>" --description="<Description>"` 创建。
12. 遵守严格 HCL 解析器约束：Pure Module Policy（禁止任何 `resource` 块，只允许 `module`、`variable`、`output`、`provider` 块；若需要资源但目录中无独立模块，必须检查是否可作为已注册模块的内置配置项，如 `module "vpc"` 中的 `private_service_access_config`）；Strict String Typing（不做布尔到字符串的隐式类型转换，如 `subnet_private_access = "true"` 而非布尔 `true`）；No Terraform Block（禁止 `terraform {}` 版本约束块，从 `providers.tf` 或 `main.tf` 中完全省略）。
13. 导入到 ADC 模板：确认模板资源存在且 HCL 满足上述约束后，调用托管的 `application_design_center:manage_application_template` MCP 工具，使用 `APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC` 操作，参数包括 `project`、`location`、`spaceId`、`applicationTemplateId`、`operation` 和 `iacModule`（含 files 列表的结构化对象，如 main.tf、variables.tf、terraform.tfvars 的内容）。
14. 导入弹性与重试：若 `IMPORT_IAC` 因瞬态错误（如 `502 Bad Gateway`、`504 Gateway Timeout`、`429 Rate Limit`）失败，不要立即重试；使用带抖动的指数退避（如等待 2s、4s、8s 加随机小数秒）；重试前先运行 `gcloud alpha design-center spaces application-templates describe` 检查导入是否已在后台成功，仅在模板未更新时才重试。
15. 捕获模板 URI：成功后按模式 `projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}` 构造 `applicationTemplateUri`。
16. 部署应用：调用托管的 `application_design_center:manage_application` MCP 工具，使用 `APPLICATION_OPERATION_DEPLOY` 操作，参数包括 `project`、`location`、`spaceId`、`applicationId`、`applicationTemplateUri` 和 `serviceAccount`。
17. 部署弹性与重试：若 `DEPLOY` 因瞬态网络或网关错误（如 `502`、`504`）失败，重试前应用带抖动的指数退避；若部署 LRO 超时或失败于状态冲突，先用 `gcloud design-center spaces applications describe` 确认应用状态再重试，避免并发冲突部署。
18. 主动 LRO 监控：工具返回 Long-Running Operation（LRO）后告知用户部署已开始；不要 sleep，使用 `gcloud design-center operations describe <operation_name>` 每 30–60 秒主动轮询直到 `done: true`。
19. 处理结果：若 `done` 为 `true` 且无 `error` 字段，进入 Phase 6；若存在 `error` 字段，分析错误类型并进入 Phase 5。
20. 迭代云解决模式：若部署失败于 `REVISION_FAILED` 或 `TERRAFORM` 错误，检查常见资源冲突——Service Account 409 Conflict（`alreadyExists`）：若模块生成的服务账号（如 `frontend-service-us-central-sa`）已存在，在本地 HCL 中禁用服务账号创建并引用现有账号：`create_service_account = false` 和 `service_account = "<existing_service_account_email>"`；Container Image 404 NotFound：确认镜像存在于注册表，测试或 hello-world 部署可使用官方公共 Google hello-world 镜像 `us-docker.pkg.dev/cloudrun/container/hello`。
21. 若部署失败不匹配上述模式，调用并执行专用 `infra-deployment-debugging` 指南（位于 references/troubleshooting_guide.md）。
22. 选择排障上下文：本地校验错误（Phase 1/2）遵循排障技能的 Case B: Raw Terraform Deployment 说明，隔离语法、编译和 plan 时校验错误；云部署失败（Phase 4）遵循 Case A: ADC Application Deployment 说明，分析 LRO 错误、获取服务日志并诊断云环境问题。
23. 应用本地优先修复：按排障技能的修复指南制定修复；强制将修复直接应用到 scratch 目录的本地 HCL 文件，重新本地校验、重新导入 HCL 并触发新部署；重新运行 `terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json`；重新运行 plan 评估（Phase 2）确保未引入新违规；用 `APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC` 重新导入修正后的 HCL 到 ADC；用 `APPLICATION_OPERATION_DEPLOY` 触发新部署。
24. 迭代阈值：重复排障、校验、导入和重新部署循环最多五（5）次；若仍失败，向用户报告完整历史和诊断信息。
25. 检索已部署资源：调用托管的 `application_design_center:manage_application` MCP 工具，使用 `APPLICATION_OPERATION_GET` 操作获取资源详情、公共端点和输出参数。
26. 健康检查：验证所有服务使用正确的容器镜像 URL，且运行时状态健康。
27. 端到端验证：执行简单演示测试（如检查公共 HTTP 端点或触发 dry-run 事务）确保 E2E 功能正常；向用户展示结果和公共 URL 以结束任务。

适用边界 · 注意事项

• 仅用于 GCP 特定的云基础设施。
• 仅用于 Application Design Center 上下文中的 Terraform 编码。