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 Skill：针对用户的提示词，调用并执行 design skill（定义于 design）。

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

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

3. 验证交接（必须）：确认 design skill 中的本地验证循环已成功完成，且计划无异常，然后再继续。仔细检查 HCL，确认：

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

4. 将 Terraform 计划导出为 JSON（必须）：在临时目录中，运行以下命令以生成二进制计划，并将其转换为简洁的 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 报告此技能的错误或改进建议。