application-design-center-design-deploy

使用 Application Design Center 设计和部署 GCP 基础设施

署名

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读 使用署名。对于直接在终端中执行的命令（切勿在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-design-center-design-deploy)" 并在 User-Agent 标头中追加 agent-skills/1.0 (skill:application-design-center-design-deploy)。

概述

此技能为 Google Cloud Platform（GCP）上的整个基础设施生命周期提供一套规范且适用于生产环境的工作流。它以由 Agent 控制的设计与验证循环取代自动化且不透明的 GAD design_infra 工具：使用模块化 Terraform 和本地 CLI 验证，然后在与 Application Design Center（ADC）注册表同步、进行部署和生命周期管理之前，提前扫描计划中的最佳实践。

始终保持首席云架构师的专业角色。将本地 Terraform 配置作为事实来源，并确保设计完全符合最佳实践，然后再将其导入云注册表。

---

目录

1. 前置条件：设置与确认
2. 阶段 1：本地基础设施设计与验证
3. 阶段 2：提前开展最佳实践评估并迭代修复
4. 阶段 3：将 IaC 导入 Application Design Center
5. 阶段 4：应用部署与监控
6. 阶段 5：排查部署失败问题
7. 阶段 6：验证与端到端测试

---

前置条件：设置与确认

开始阶段 1 之前，必须执行以下设置步骤：

1. 确认目标项目与位置：

   • 明确询问用户，确认目标 GCP 项目 ID 和 位置（区域）。

   • 如果用户未指定位置，请使用 us-central1 作为 默认值。

   • 验证本地环境已设置活动项目：

     gcloud config set project <project_id>
     

---

阶段 1：本地基础设施设计与验证

目标：将用户需求和代码库特征转化为一份经过 100% 验证、安全且可编译的 Terraform 配置。

1. 调用 design 技能：针对用户的提示词，调用并执行 design 技能（定义见 design）。

   • design 技能将在专用临时目录中自主执行代码库分析、查询目录注册表、规划、生成 HCL，以及本地 CLI 验证循环（terraform init、validate、plan）。

2. 定位已验证的 HCL：找到 design 技能保存已验证且可编译 Terraform 文件的临时目录（例如， scratch/tf_validate_<session_id>/）。

3. 验证交接（必须）：确保 design 技能中的本地验证循环已成功完成，并生成无异常的 plan，然后再继续。仔细检查 HCL，确认：

   • 密钥安全策略：确认 terraform.tfvars 或 HCL 资源块中没有明文凭据、密码或硬编码密钥。所有敏感输入都必须通过 GCP Secret Manager 接入。
   • 状态隔离策略：确认 HCL 文件中没有远程后端块（例如 backend "gcs" {}）。验证期间，状态必须保留在临时文件夹的本地，以便导入时由 ADC 处理远程状态注册表。
   • 修复：如果发现任何违规情况，请在 HCL 中修正，重新运行本地验证，并再次确认。不得继续使用未经验证或不安全的代码。

4. 将 Terraform Plan 导出为 JSON（必须）：在临时目录中运行以下命令，生成二进制 plan 并将其转换为干净的 JSON 表示：

   terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
   

   确认已在临时目录中成功写入 tfplan.json 文件。

---

阶段 2：左移最佳实践评估与迭代式修复

目标：使用原生 ADC 计划评估 API，在将本地计划导入云注册表之前，验证其是否符合安全性、成本和可靠性基准。

1. 发现 Space ID（必须）：在运行评估或创建模板之前，必须动态发现目标位置中活跃的 ADC Space ID：

   • 列出 Spaces：运行命令：

     gcloud design-center spaces list --project=<project_id> --location=<location>
     

   • 选择 Space：解析输出以确定活跃的 space（例如 test-deploy 或 googlespace）。如果存在多个 space，请向用户确认。如果不存在 space，请询问用户或创建一个：

     gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>
     

2. 通过 gcloud 执行计划评估：使用发现的 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
   

3. 分析发现项：以清晰的表格形式向用户展示所有发现项，详细说明具体违规项、资源范围及相应的严重级别。

4. 本地修复循环：

   • 不要尝试导入或提交不安全的代码。

   • 编辑临时目录中的本地 HCL 文件，修复报告中的违规项（例如，添加加密密钥、启用 OS Login 或限制 IAM 范围）。

   • 重新运行阶段 1 的本地验证并导出计划：

     terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
     

   • 重新运行步骤 2 中所示的计划评估命令。

5. 退出标准：

   • 解决所有高危/严重发现项，或记录可接受的权衡。
   • 最多进行三（3）次迭代尝试。评估通过或结果可接受后，继续阶段 3。

---

阶段 3：将 IaC 导入 Application Design Center

目标：将经过全面验证且符合最佳实践的本地 HCL 配置同步到 ADC 云注册表，以创建可部署的模板资源。

1. 验证或创建 Application Template（必须）：导入 HCL 之前，必须确保已在发现的 ADC space 中创建父级 Application Template 资源。

   • 检查是否存在：运行 gcloud design-center spaces application-templates describe <template_id> --space=<space_id> --project=<project_id> --location=<location>，检查模板是否存在。

   • 若不存在则创建：如果 describe 命令返回 NOT_FOUND 错误，请先运行以下命令创建模板资源：

     gcloud design-center spaces application-templates create <template_id> --space=<space_id> --project=<project_id> --location=<location> --display-name="<Name>" --description="<Description>"
     

2. 严格的 HCL 解析器约束（关键）：调用导入操作之前，请确保本地 HCL 符合 ADC 注册表严格的接收规则：

   • 纯模块策略（无资源块）： ADC 解析器严格 禁止在导入的 HCL 中包含任何 resource 块。只允许使用 module、variable、output 和 provider 块。如果需要某项 资源（例如 Private Service Access 对等连接），但目录中没有为其注册 独立模块，则 MUST 检查该资源是否作为现有已注册模块中的内置配置选项受支持 （例如，在 module "vpc" 中设置 private_service_access_config）。
   • 严格的字符串类型： ADC 解析器不会将布尔值隐式转换为字符串。 例如，子网私有访问必须声明为字符串字面量：subnet_private_access = "true"，而不能 声明为布尔值 true。
   • 无 Terraform 块： 解析器严格禁止使用 terraform {} 版本约束块。请从 providers.tf 或 main.tf 中完全省略该块。

3. 导入到 ADC 模板：确认模板资源存在且 HCL 已根据上述约束验证后，调用托管的 application_design_center:manage_application_template MCP 工具，并使用 APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC 操作：

   • 参数：

     • project：目标项目 ID。

     • location：GCP 部署区域（例如，us-central1）。

     • spaceId：已发现的 ADC 空间 ID。

     • applicationTemplateId：应用模板的唯一名称。

     • operation：APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC

     • iacModule：包含文件列表的结构化对象：

       {
         "files": [
           { "name": "main.tf", "content": "<content of main.tf>" },
           { "name": "variables.tf", "content": "<content of variables.tf>" },
           { "name": "terraform.tfvars", "content": "<content of terraform.tfvars>" }
         ]
       }
       

   • 弹性与重试（强制要求）：

     • 如果 IMPORT_IAC 调用因暂时性错误（例如，502 Bad Gateway、504 Gateway Timeout 或 429 Rate Limit）失败，请勿 立即重试。
     • 使用带抖动的指数退避（例如，等待 2s、4s、8s， 并额外加入随机的秒数小数部分）。
     • 重试前验证修订版本：如果发生超时，请先调用 gcloud alpha design-center spaces application-templates describe，检查导入是否已在后台成功。仅当模板未更新时才重试。

4. 获取模板 URI：成功后，模板资源即会在您的空间中创建。请按以下格式构造 applicationTemplateUri： projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}

---

第 4 阶段：应用部署与监控

目标：将经过验证且符合最佳实践的应用模板部署到 GCP 环境中。

1. 部署应用：使用 APPLICATION_OPERATION_DEPLOY 操作调用托管的 application_design_center:manage_application MCP 工具：
   • 参数：
     • project：目标项目 ID。
     • location：目标部署位置。
     • spaceId：目标空间 ID。
     • applicationId：已部署应用实例的唯一 ID。
     • applicationTemplateUri：第 3 阶段中确定的 URI。
     • serviceAccount：部署服务账号。
   • 弹性与重试（必须）：
     • 如果 DEPLOY 操作因暂时性网络或网关错误（例如 502、504）而失败，请在重试前应用带抖动的指数退避。
     • 如果部署 LRO 超时或因状态冲突而失败，请使用 gcloud design-center spaces applications describe 验证应用状态，确认其状态后再重试部署调用，以避免并发部署冲突。
2. 主动监控 LRO：
   • 该工具会返回一个长时间运行操作（LRO）。请告知用户部署已开始。
   • 请勿休眠等待部署状态轮询。使用命令 gcloud design-center operations describe <operation_name> 每隔 30–60 秒主动轮询 LRO，直到 done: true。
3. 处理结果：
   • 成功：如果 done 为 true 且不存在 error 字段，请继续第 6 阶段。
   • 失败：如果存在 error 字段，请分析错误类型并继续第 5 阶段。

---

阶段 5：排查部署失败

目标：使用专用排障技能和成熟的云端问题解决模式，逐步诊断并修复部署失败。

1. 迭代式云端问题解决模式（关键）：如果部署因 REVISION_FAILED 或 TERRAFORM 错误而失败，请检查以下常见资源冲突：

   • 服务账号 409 冲突（alreadyExists）：如果部署失败的原因是模块生成的服务账号（例如 frontend-service-us-central-sa）已存在于项目中，请在本地 HCL 中禁用服务账号创建，并引用现有服务账号：

     create_service_account = false
     service_account        = "<existing_service_account_email>"
     

   • 容器镜像 404 NotFound：如果部署因找不到容器镜像而失败，请确认镜像存在于你的注册表中。对于测试或 hello-world 部署，请使用官方公开的 Google hello-world 镜像： us-docker.pkg.dev/cloudrun/container/hello

2. 委托给排障技能：如果发生的部署失败与上述模式不符，请调用并执行专用的 infra-deployment-debugging 指南（位于 infra-deployment-debugging）。

3. 选择排障上下文：

   • 本地验证错误（阶段 1/2）：遵循排障技能中的 案例 B：原始 Terraform 部署 说明，隔离语法、编译和计划阶段的验证错误。
   • 云端部署失败（阶段 4）：遵循排障技能中的 案例 A：ADC 应用部署 说明，分析 LRO 错误、获取服务日志并诊断云环境问题。

4. 优先在本地修复：

   • 遵循排障技能中的修复指南，制定修复方案。

   • 必须：直接在临时目录中的本地 HCL 文件应用修复，重新运行本地验证，重新导入 HCL，并触发新的部署。

   • 重新运行阶段 1 的本地验证和计划导出：

     terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
     

   • 重新运行计划评估（阶段 2），确保没有引入新的违规项。

   • 使用 APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC 将修正后的 HCL 重新导入 ADC。

   • 使用 APPLICATION_OPERATION_DEPLOY 触发新的部署。

5. 迭代次数上限：最多重复排障、验证、导入和重新部署流程五（5）次。如果仍然失败，请向用户报告完整的历史记录和诊断信息。

---

阶段 6：验证与端到端测试

目标：确认已部署的服务运行正常且功能完整。

1. 获取已部署资源：调用托管的 application_design_center:manage_application MCP 工具，并执行 APPLICATION_OPERATION_GET 操作，以获取资源详情、公共端点和输出参数。
2. 运行状况检查：确认所有服务都使用正确的容器镜像 URL，且运行时状态正常。
3. 端到端验证：进行简单的演示测试（例如，检查公共 HTTP 端点或触发试运行交易），以确保端到端功能正常。向用户展示结果和公共 URL，作为任务的结束。

报告问题

请在 Google Skills Issues 报告此技能的错误或改进建议。