design-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Custom Infrastructure Design and Deployment Skill

自定义基础设施设计与部署Skill

Overview

概述

This skill provides a prescriptive, production-grade workflow for the entire infrastructure lifecycle on Google Cloud Platform (GCP). It replaces the automated, opaque-box GAD
design_infra
tool with an agent-controlled design and validation loop utilizing modular Terraform and local CLI validation, followed by a shifted-left best practices plan scan prior to synchronization with the Application Design Center (ADC) registry for deployment and lifecycle management.
Always maintain the persona of a Principal Cloud Architect. Keep the local Terraform configuration as the source of truth, and ensure the design is fully compliant with best practices before importing it into the cloud registry.

本Skill为Google Cloud Platform(GCP)上的整个基础设施生命周期提供了一套规范的、生产级工作流。它采用基于模块化Terraform和本地CLI验证的Agent控制的设计与验证循环,替代了自动化的黑盒GAD
design_infra
工具,并在与Application Design Center(ADC)注册表同步以进行部署和生命周期管理之前,执行左移最佳实践计划扫描
始终保持首席云架构师的角色定位。将本地Terraform配置作为事实来源,并确保在将设计导入云注册表之前完全符合最佳实践要求。

Index

目录

Pre-requisites: Setup & Confirmation

前置条件:设置与确认

Before executing Phase 1, you must perform the following setup steps:
  1. Confirm Target Project & Location:
    • Explicitly ask the user to confirm the target GCP project ID and location (region).
    • If the user does not specify a location, use
      us-central1
      as the default.
    • Verify that your local environment has the active project set:
      bash
      gcloud config set project <project_id>

在执行阶段1之前,你必须完成以下设置步骤:
  1. 确认目标项目与位置:
    • 明确要求用户确认目标GCP的项目ID位置(区域)。
    • 如果用户未指定位置,默认使用**
      us-central1
      **。
    • 验证本地环境已设置好活跃项目:
      bash
      gcloud config set project <project_id>

Phase 1: Local Infrastructure Design & Validation

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

Goal: Transform user requirements and codebase characteristics into a 100% validated, secure, and compile-ready Terraform configuration locally.
  1. Invoke the
    design
    Skill
    : Call and execute the
    design
    skill (defined in design) for the user's prompt.
    • The
      design
      skill will autonomously perform the Codebase Analysis, query the catalog registry, planning, HCL generation, and local CLI validation loop (
      terraform init
      ,
      validate
      ,
      plan
      ) in a dedicated scratch directory.
  2. Locate Validated HCL: Identify the scratch directory where the
    design
    skill saved the validated, compile-ready Terraform files (e.g.,
    scratch/tf_validate_<session_id>/
    ).
  3. Verify Handover (MANDATORY): Ensure that the local validation loop in the
    design
    skill completed successfully with a clean plan before proceeding. Meticulously inspect the HCL to verify:
    • Secret-Safe Policy: Confirm that no plaintext credentials, passwords, or hardcoded secrets are written in
      terraform.tfvars
      or HCL resource blocks. All sensitive inputs must be wired through GCP Secret Manager.
    • State Isolation Policy: Confirm that there is no remote backend block (e.g.,
      backend "gcs" {}
      ) in the HCL files. State must remain local in the scratch folder during validation, allowing ADC to handle the remote state registry upon import.
    • Remediation: If any violations are found, correct them in the HCL, re-run local validation, and verify again. Do not proceed with unvalidated or insecure code.
  4. Export Terraform Plan to JSON (MANDATORY): In the scratch directory, run the following commands to generate a binary plan and convert it into a clean JSON representation:
    bash
    terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
    Verify that the
    tfplan.json
    file is successfully written in your scratch directory.

目标:将用户需求和代码库特征转换为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格式:
    bash
    terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
    确认
    tfplan.json
    文件已成功写入临时目录。

Phase 2: Shifted-Left Best Practices Assessment & Iterative Remediation

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

Goal: Validate the local plan's alignment with security, cost, and reliability benchmarks BEFORE importing it into the cloud registry, using the native ADC plan assessment API.
  1. Discover Space ID (MANDATORY): Before running the assessment or creating templates, you must dynamically discover the active ADC Space ID in your target location:
    • List Spaces: Run the command:
      bash
      gcloud design-center spaces list --project=<project_id> --location=<location>
    • Select Space: Parse the output to identify the active space (e.g.,
      test-deploy
      or
      googlespace
      ). If multiple spaces exist, ask the user to confirm. If no space exists, ask the user or create one:
      bash
      gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>
  2. Execute Plan Assessment via gcloud: Run the plan-based assessment using the discovered Space ID and your exported
    tfplan.json
    file. Execute the command directly in your terminal:
    bash
    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. Analyze Findings: Present all findings to the user in a clean tabular format, detailing specific violations, resource scopes, and associated severity levels.
  4. Local Remediation Loop:
    • Do not attempt to import or commit insecure code.
    • Edit your local HCL files in the scratch directory to fix the reported violations (e.g., adding encryption keys, enabling OS Login, or restricting IAM scopes).
    • Re-run Phase 1 local validation and plan export:
      bash
      terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
    • Re-run the plan assessment command shown in step 2.
  5. Exit Criteria:
    • All high/critical findings resolved, or acceptable trade-offs documented.
    • Maximum of three (3) iterative attempts reached. Once clean or acceptable, proceed to Phase 3.

目标:在将本地计划导入云注册表之前,使用原生ADC计划评估API验证其是否符合安全、成本和可靠性基准。
  1. 发现空间ID(必填):在运行评估或创建模板之前,你必须动态发现目标位置中的活跃ADC空间ID:
    • 列出空间:运行命令:
      bash
      gcloud design-center spaces list --project=<project_id> --location=<location>
    • 选择空间:解析输出以识别活跃空间(例如
      test-deploy
      googlespace
      )。如果存在多个空间,请用户确认。如果不存在空间,请用户指定或创建一个:
      bash
      gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>
  2. 通过gcloud执行计划评估:使用发现的空间ID和导出的
    tfplan.json
    文件执行基于计划的评估。直接在终端中执行命令:
    bash
    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的本地验证和计划导出:
      bash
      terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
    • 重新运行步骤2中所示的计划评估命令。
  5. 退出条件:
    • 所有高/严重级别问题已解决,或已记录可接受的权衡方案。
    • 已达到最多三次(3次)迭代尝试。一旦问题解决或可接受,进入阶段3。

Phase 3: Import IaC to Application Design Center

阶段3:将IaC导入Application Design Center

Goal: Synchronize the fully validated and best-practice-compliant local HCL configuration with the ADC cloud registry to establish the deployable template resource.
  1. Verify or Create the Application Template (MANDATORY): Before importing the HCL, you must ensure the parent Application Template resource exists in the discovered ADC space.
    • Check Existence: Run
      gcloud design-center spaces application-templates describe <template_id> --space=<space_id> --project=<project_id> --location=<location>
      to check if the template exists.
    • Create if Missing: If the describe command returns a
      NOT_FOUND
      error, create the template resource first by running:
      bash
      gcloud design-center spaces application-templates create <template_id> --space=<space_id> --project=<project_id> --location=<location> --display-name="<Name>" --description="<Description>"
  2. Strict HCL Parser Constraints (CRITICAL): Before calling the import operation, ensure your local HCL complies with the ADC registry's strict ingestion rules:
    • Pure Module Policy (No Resource Blocks): The ADC parser strictly prohibits any
      resource
      blocks
      inside the imported HCL. Only
      module
      ,
      variable
      ,
      output
      , and
      provider
      blocks are allowed. If a resource is required (e.g. Private Service Access peering) but no standalone module is registered for it in the catalog, you MUST check if it is supported as a built-in configuration option inside an existing registered module (e.g. setting
      private_service_access_config
      inside
      module "vpc"
      ).
    • Strict String Typing: The ADC parser does not perform implicit type coercion from boolean to string. For example, subnet private access must be declared as a literal string:
      subnet_private_access = "true"
      , NOT as a boolean
      true
      .
    • No Terraform Block: The parser strictly prohibits the
      terraform {}
      version constraint block. Omit it entirely from
      providers.tf
      or
      main.tf
      .
  3. Import to ADC Template: Once the template resource is confirmed to exist and the HCL is validated against the above constraints, invoke the hosted
    application_design_center:manage_application_template
    MCP tool with the
    APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC
    operation:
    • Arguments:
      • project
        : The target project ID.
      • location
        : The GCP deployment region (e.g.,
        us-central1
        ).
      • spaceId
        : The discovered ADC space ID.
      • applicationTemplateId
        : A unique name for your application template.
      • operation
        :
        APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC
      • iacModule
        : A structured object containing the files list:
        json
        {
          "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>" }
          ]
        }
    • Resilience & Retries (MANDATORY):
      • If the
        IMPORT_IAC
        call fails due to a transient error (e.g.,
        502 Bad Gateway
        ,
        504 Gateway Timeout
        , or
        429 Rate Limit
        ), do not immediately retry.
      • Use exponential backoff with jitter (e.g., waiting 2s, 4s, 8s plus a random fraction of a second).
      • Verify Revision before Retry: If a timeout occurred, first call
        gcloud alpha design-center spaces application-templates describe
        to check if the import actually succeeded in the background. Only retry if the template was not updated.
  4. Capture Template URI: Upon success, this establishes the template resource in your space. Construct the
    applicationTemplateUri
    using the pattern:
    projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}

目标:将完全验证且符合最佳实践的本地HCL配置与ADC云注册表同步,以建立可部署的模板资源。
  1. 验证或创建应用模板(必填):在导入HCL之前,你必须确保父应用模板资源存在于已发现的ADC空间中。
    • 检查是否存在:运行
      gcloud design-center spaces application-templates describe <template_id> --space=<space_id> --project=<project_id> --location=<location>
      以检查模板是否存在。
    • 不存在则创建:如果describe命令返回
      NOT_FOUND
      错误,先运行以下命令创建模板资源:
      bash
      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对等连接)但目录中没有注册独立模块,你必须检查它是否作为现有注册模块中的内置配置选项被支持(例如在
      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
        : 包含文件列表的结构化对象:
        json
        {
          "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
        )失败,不要立即重试
      • 使用带抖动的指数退避(例如等待2秒、4秒、8秒再加上随机的几分之一秒)。
      • 重试前验证版本:如果发生超时,先调用
        gcloud alpha design-center spaces application-templates describe
        检查导入是否在后台实际成功。仅当模板未更新时才重试。
  4. 捕获模板URI:成功后,将在你的空间中建立模板资源。使用以下模式构造
    applicationTemplateUri
    projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}

Phase 4: Application Deployment & Monitoring

阶段4:应用部署与监控

Goal: Deploy the validated, best-practice-compliant application template to the GCP environment.
  1. Deploy Application: Invoke the hosted
    application_design_center:manage_application
    MCP tool with the
    APPLICATION_OPERATION_DEPLOY
    operation:
    • Arguments:
      • project
        : Target project ID.
      • location
        : Target deployment location.
      • spaceId
        : Target space ID.
      • applicationId
        : A unique ID for the deployed application instance.
      • applicationTemplateUri
        : The URI established in Phase 3.
      • serviceAccount
        : The deployment service account.
    • Resilience & Retries (MANDATORY):
      • If the
        DEPLOY
        operation fails with transient network or gateway errors (e.g.,
        502
        ,
        504
        ), apply exponential backoff with jitter before retrying.
      • If the deployment LRO times out or fails with a state conflict, verify the application status using
        gcloud design-center spaces applications describe
        to confirm its status before retrying the deploy call, avoiding concurrent conflicting deployments.
  2. Active LRO Monitoring:
    • The tool returns a Long-Running Operation (LRO). Inform the user that the deployment has started.
    • Do not sleep during deployment status polling. Poll the LRO actively every 30–60 seconds until
      done: true
      using the command
      gcloud design-center operations describe <operation_name>
      .
  3. Handle Results:
    • Success: If
      done
      is
      true
      and there is no
      error
      field, proceed to Phase 6.
    • Failure: If an
      error
      field is present, analyze the error type and proceed to Phase 5.

目标:将经过验证且符合最佳实践的应用模板部署到GCP环境中。
  1. 部署应用:调用托管的
    application_design_center:manage_application
    MCP工具并使用
    APPLICATION_OPERATION_DEPLOY
    操作:
    • 参数:
      • project
        : 目标项目ID。
      • location
        : 目标部署位置。
      • spaceId
        : 目标空间ID。
      • applicationId
        : 已部署应用实例的唯一ID。
      • applicationTemplateUri
        : 阶段3中建立的URI。
      • serviceAccount
        : 部署服务账号。
    • 弹性与重试(必填):
      • 如果
        DEPLOY
        操作因临时网络或网关错误(例如
        502
        504
        )失败,在重试前应用带抖动的指数退避
      • 如果部署LRO超时或因状态冲突失败,使用
        gcloud design-center spaces applications describe
        验证应用状态,确认后再重试部署调用,避免并发冲突部署。
  2. 主动LRO监控:
    • 工具会返回一个长期运行操作(LRO)。告知用户部署已开始。
    • 不要休眠,在部署状态轮询期间,每30–60秒主动轮询LRO,直到
      done: true
      ,使用命令
      gcloud design-center operations describe <operation_name>
  3. 处理结果:
    • 成功:如果
      done
      true
      且没有
      error
      字段,进入阶段6。
    • 失败:如果存在
      error
      字段,分析错误类型并进入阶段5。

Phase 5: Troubleshoot Deployment Failures

阶段5:排查部署故障

Goal: Diagnose and remediate deployment failures iteratively using the specialized troubleshooting skill and established cloud resolution patterns.
  1. Iterative Cloud Resolution Patterns (CRITICAL): If the deployment fails with a
    REVISION_FAILED
    or
    TERRAFORM
    error, check for these common resource conflicts:
    • Service Account 409 Conflict (
      alreadyExists
      ):
      If the deployment fails because a service account generated by the module (e.g.
      frontend-service-us-central-sa
      ) already exists in the project, remediate the local HCL by disabling service account creation and referencing the existing one:
      hcl
      create_service_account = false
      service_account        = "<existing_service_account_email>"
    • Container Image 404 NotFound: If the deployment fails because a container image is not found, confirm that the image exists in your registry. For testing or hello-world deployments, leverage the official public Google hello-world image:
      us-docker.pkg.dev/cloudrun/container/hello
  2. Delegate to the Troubleshooting Skill: If a deployment failure occurs and does not match the above patterns, invoke and execute the specialized
    infra-deployment-debugging
    skill (located in infra-deployment-debugging).
  3. Select the Troubleshooting Context:
    • For Local Validation Errors (Phase 1/2): Follow Case B: Raw Terraform Deployment instructions in the troubleshooting skill to isolate syntax, compilation, and plan-time validation errors.
    • For Cloud Deployment Failures (Phase 4): Follow Case A: ADC Application Deployment instructions in the troubleshooting skill to analyze LRO errors, retrieve service logs, and diagnose cloud environment issues.
  4. Apply Local-First Remediation:
    • Follow the troubleshooting skill's remediation guides to formulate a fix.
    • MANDATORY: Apply the fix directly to your local HCL files in the scratch directory, re-run local validation, re-import the HCL, and trigger a new deployment.
    • Re-run Phase 1 local validation and plan export:
      bash
      terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json
    • Re-run the plan assessment (Phase 2) to ensure no new violations are introduced.
    • Re-import the corrected HCL to ADC using
      APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC
      .
    • Trigger a new deployment using
      APPLICATION_OPERATION_DEPLOY
      .
  5. Iteration Threshold: Repeat the troubleshooting, validation, import, and redeployment cycle up to five (5) times. If it still fails, report the full history and diagnostics to the user.

目标:使用专门的排障Skill和已建立的云解决方案模式,迭代诊断并修复部署故障。
  1. 迭代云解决方案模式(关键):如果部署因
    REVISION_FAILED
    TERRAFORM
    错误失败,检查以下常见资源冲突:
    • 服务账号409冲突(
      alreadyExists
      :如果部署失败是因为模块生成的服务账号(例如
      frontend-service-us-central-sa
      )已存在于项目中,通过禁用服务账号创建并引用现有账号来修复本地HCL:
      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. 委托给排障Skill:如果发生部署故障且不符合上述模式,调用并执行专门的
    infra-deployment-debugging
    Skill(位于infra-deployment-debugging)。
  3. 选择排障上下文:
    • 针对本地验证错误(阶段1/2):遵循排障Skill中的案例B:原生Terraform部署说明,隔离语法、编译和计划时验证错误。
    • 针对云部署故障(阶段4):遵循排障Skill中的案例A:ADC应用部署说明,分析LRO错误、检索服务日志并诊断云环境问题。
  4. 应用本地优先修复:
    • 遵循排障Skill的修复指南制定解决方案。
    • 必填:直接在临时目录的本地HCL文件中应用修复,重新运行本地验证,重新导入HCL并触发新的部署。
    • 重新运行阶段1的本地验证和计划导出:
      bash
      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次)。如果仍然失败,向用户报告完整的历史记录和诊断信息。

Phase 6: Verification & E2E Testing

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

Goal: Confirm that the deployed services are healthy and fully functional.
  1. Retrieve Deployed Resources: Invoke the hosted
    application_design_center:manage_application
    MCP tool with the
    APPLICATION_OPERATION_GET
    operation to retrieve the resource details, public endpoints, and output parameters.
  2. Health Check: Verify that all services are using the correct container image URLs and that their runtime status is healthy.
  3. E2E Validation: Conduct a simple demo test (e.g., checking public HTTP endpoints or triggering a dry-run transaction) to ensure E2E functionality. Present the results and public URLs to the user to conclude the task.
目标:确认已部署的服务健康且功能完整。
  1. 检索已部署资源:调用托管的
    application_design_center:manage_application
    MCP工具并使用
    APPLICATION_OPERATION_GET
    操作,检索资源详情、公共端点和输出参数。
  2. 健康检查:验证所有服务是否使用正确的容器镜像URL,且运行状态健康。
  3. 端到端验证:执行简单的演示测试(例如检查公共HTTP端点或触发空运行事务)以确保端到端功能正常。向用户展示结果和公共URL以完成任务。

Reporting Issues

问题反馈

Report bugs or improvements for this skill at Google Skills Issues.
请在Google Skills Issues报告本Skill的漏洞或改进建议。