尧图网站建设 
基于 Application Design Center 的模块化 GCP Terraform 架构设计指南四阶段 Agentic 设计管线实战【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文是 design_guide.md 的完整展开围绕 GCP Application Design CenterADC框架下的简化模块化 Terraform 架构设计技能Simplified GCP Modular Terraform Architect Skill展开。该技能以 Agent 自主执行的四阶段生成管线为核心意图摄取与目录查询 → 高层架构规划 → 模块优先生成与 CLI 校验 → 语义审查与交接将设计 → 校验 → 修正闭环固化到生成流程中。读完本文你将掌握如何在 ADC 中查询私有/公共目录组件、提取组件 gitSource 元数据构造固定版本的模块 source、规划模块间输出绑定、运行terraform init/validate/plan本地校验循环以及最终输出经语义审查的完整 HCL 交接产物。一、技能定位与整体工作流该 skill 处理的是GCP 云架构设计与本地校验适用于以下场景来自 SKILL.md 中design技能的描述设计模块化 Terraform 架构编写本地 HCL 代码通过terraform validate校验 HCL通过terraform plan规划 HCL以及后续向 ADC 注册表导入模板、部署与排障由同目录的部署类引用文档承接。它不适用于模板部署、计划评估或部署失败排障——这些属于application-design-center-design-deploy主技能的后续阶段。本文聚焦于其内部引用的design设计指南即 design_guide.md。整条设计管线是一个带反馈回路的四阶段流程四个阶段必须严格按顺序执行不可跳过当阶段 4 的语义审查判定配置未能完全满足用户的架构目标或意图时必须回退到阶段 2 重新规划并重新生成。二、三条强制架构约束贯穿全程的底线所有生成的配置在追求模块化结构的同时必须遵守以下命名与 HCL 风格约束默认网络与子网除非另有指定目标project_id中应使用预先存在的、均名为default的 VPC 网络和子网。密钥安全策略强制绝不允许在 HCL 代码或terraform.tfvars中写入明文密码、API Key 或凭据。所有密钥必须通过terraform-google-secret-manager模块声明为 GCP Secret Manager 资源并由目标服务动态引用。状态隔离策略强制校验期间将 Terraform 状态保持在 scratch 文件夹的本地状态。绝不生成远程 backend 块如backend gcs {}远程状态由上层编排器/部署注册表动态管理。这三条约束在主技能 SKILL.md 的阶段 1 交接核验中再次被强调在进入后续流程前必须逐行检查 HCL确认无明文凭据、无远程 backend 块一旦发现违规必须就地修正并重新校验。三、Phase 1意图摄取与目录查询Ingest Intent Catalog Query3.1 加载输入摄取用户的目标与指令作为后续所有阶段的决策基础。3.2 查询目录注册表私有 公共为补充设计信息需要通过原生manage_catalogMCP 工具、以CATALOG_OPERATION_LIST_COMPONENTS操作同时检索项目的自定义私有目录与 Google 公共目录。查询私有目录目标空间ServerNameapplication_design_centerToolNamemanage_catalogArguments{ project: project_id, location: location, spaceId: space_id, operation: CATALOG_OPERATION_LIST_COMPONENTS }查询公共 Google 目录ServerNameapplication_design_centerToolNamemanage_catalogArguments{ project: gcpdesigncenter, location: us-central1, spaceId: googlespace, catalogId: googlecatalog, operation: CATALOG_OPERATION_LIST_COMPONENTS }优先级规则必须优先使用目标空间中的私有目录模板而非公共 Google 模板以确保项目级定制被尊重。3.3 获取模块详情调用原生manage_catalogMCP 工具通过CATALOG_OPERATION_GET_COMPONENT_METADATA操作获取包含 inputs、outputs 与依赖关系的模块详细元数据或使用CATALOG_OPERATION_GET_COMPONENT_IAC直接获取底层 Terraform 源码{ project: project_id, location: location, spaceId: space_id, catalogTemplateId: short_module_id, catalogTemplateRevisionId: revision_id, operation: CATALOG_OPERATION_GET_COMPONENT_METADATA }约束只传短模块 ID例如cloud-run-job即完整资源名的最后一段不要传 list 命令返回的完整资源名路径。3.4 提取 gitSource 并构造固定版本的 source重要为了让本地 HCL 声明与 Design Center 注册表校验的版本约束完全一致必须从注册表提取精确的 Git 仓库 tag并用于 HCL 模块的source字段gitSource元数据块包含refTag、repo、dir会直接返回在manage_catalogMCP 工具的输出中位于gitSource字段下。如需回退到 CLI 描述修订详情可直接用 MCP 工具返回的修订 URI 执行describe命令gcloud design-center spaces catalogs templates revisions describe revision_uri具体两步操作提取gitSource块中的字段gitSource: dir: modules/v2 refTag: v0.33.0 repo: GoogleCloudPlatform/terraform-google-cloud-run按github.com/repo//dir?refrefTag模式构造 HCLsourceURIsource github.com/GoogleCloudPlatform/terraform-google-cloud-run//modules/v2?refv0.33.0这条规则与生成器指令中的Mandatory Version Pinning强制版本固定完全呼应——generator_instructions.md 明确要求所有模块source必须使用 Git/GitHub 仓库路径去掉https://前缀的github.com/...而非 Terraform Registry 格式且必须携带与注册表refTag完全一致的?refvX.Y.Z参数禁止无版本路径。四、Phase 2高层架构规划High-Level Architecture Planning4.1 强制资源初始化在制定任何方案之前必须先阅读 planner_instructions.md 中的指令确保其进入活动上下文后方可继续。从源码角度该文档定义的 Planner 角色是企业级 GCP 解决方案架构师其核心规划循环为三步查询注册表与架构 → 转换为 TF 模块/资源信息 → 生成模块优先的 HCL。这与 design_guide 的阶段 2 职责完全一致。4.2 设计高层架构基于阶段 1 识别出的模块规划连接关键模块化构建块VPC、Compute、Databases、Security的设计拓扑。4.3 制定集成模式决策确定核心模式布局决策例如 GKE 与 Cloud Run 的计算模型选型、存储引擎、网络边界、私有互联、数据库托管结构并基于可用模块落地。遵循 Google 最佳实践例如始终使用 Secret Manager 存储和引用数据库凭据而不是把口令作为输入参数传入私有连接优先使用 Private Service Connect 而非公共访问。4.4 盘点可复用的既有 TF 模块检查目录中是否已有可复用的 TF 模块以理解可用的构建块从而拼出匹配用户意图的端到端方案。目录包含 GCP 发布的公共目录与客户自有的私有目录当公共与私有目录出现重复模块时始终优先选择私有目录组件/模块。通过manage_catalogMCP 工具的CATALOG_OPERATION_GET_COMPONENT_METADATA操作核验所选模块的 inputs、outputs、必填项与引用输出{ project: gcpdesigncenter, location: us-central1, spaceId: googlespace, catalogId: googlecatalog, operation: CATALOG_OPERATION_GET_COMPONENT_METADATA, catalogTemplateId: module_id }约束使用短模块 ID资源名的最后一段例如cloud-run-job而非以projects/...开头的完整资源路径。若查询私有目录相应更新project、spaceId与catalogId参数。4.5 审查端到端解决方案模板审查 GCP 发布的最佳架构解决方案以及客户组织自己发布的解决方案将其作为可参考的参考架构。要探索可用模板可运行本地 CLI 脚本list_terraform_templates查看是否存在可作设计基线的既有应用模板。必须传入目标项目 ID 与空间 ID以同时检索公共 Google 模板与私有模板python3 scripts/list_terraform_templates.py --projectproject_id --space_idspace_id --catalog_idcatalog_id从源码看该脚本list_terraform_templates.py的执行逻辑恰好印证了文档的优先级规则它先查询私有目录default-catalog为默认 catalog再查询 Google 公共目录固定为gcpdesigncenter/us-central1/googlespace/googlecatalog并通过seen_template_ids去重——私有模板先处理因此天然排在返回列表前面且仅保留templateCategory APPLICATION_TEMPLATE的条目最终为每个条目标注source: private或source: google。优先级规则返回列表中私有应用模板排在最前标记为source: private。若存在合适的私有模板必须优先于标记为source: google的公共 Google 模板使用。4.6 获取 Terraform 模板运行本地 CLI 脚本fetch_terraform_template将基线模板配置拉取到本地工作区。必须传入目标项目 ID 与空间 IDpython3 scripts/fetch_terraform_template.py template_id --projectproject_id --space_idspace_id --out_dirtarget_directory_path输出目录不存在时会自动创建。从源码看该脚本fetch_terraform_template.py的完整链路为解析输入支持projects/...完整资源路径或短 ID→gcloud alpha design-center ... templates describe获取latestRevisionId→ 描述修订获取applicationTemplateRevisionSource→gcloud alpha design-center ... revisions generate生成 IaC 并返回 GCS URI →gcloud storage cp下载到本地临时目录 → 根据是否指定--out_dir决定落盘或直接打印全部 HCL 内容到 stdout每个文件以# 文件名 分隔。它的参数解析测试fetch_terraform_template_test.py覆盖了短 ID 默认解析到公共目录、以及完整路径解析两种情形验证了两种输入模式的行为。4.7 复核规划原则交叉核对 planner_instructions.md 中的规划指令。该文档还强调了规划阶段的关键动作将匹配到的模块视为基线优先用模块、仅在无对应模块时回退到直接资源通过CATALOG_OPERATION_GET_COMPONENT_METADATA核验模块输入输出预规划模块间 output-to-input 绑定禁止硬编码连接关系严格使用直接输出module.exporter_name.output_name并在生成文件前固化映射与拓扑决策。五、Phase 3模块优先生成与 CLI 校验循环Module-Only Generator CLI Validation Loop5.1 强制资源初始化在编写任何 HCL 之前必须阅读 generator_instructions.md 中的指令确保其进入活动上下文。5.2 生成原始 HCL编写标准 Terraform 代码尽可能优先使用 module 块仅在无合适模块时使用直接资源并遵循已加载指令中的规则。生成器指令细化了关键约束模块优先于直接资源直接resource块仅在无已批准模块可用、或作为模块化配置的必要补充时才允许禁止复杂 HCL 逻辑除非明确要求不要使用迭代语法for_each、count、三元条件逻辑或locals块保持结构扁平化与声明式必须包含标准terraform块声明hashicorp/google等必需 provider 及最低版本与provider google块默认目标项目与区域否则会破坏阶段 3 的密闭本地校验例程唯一模块实例命名关键为避免多实例部署或失败后重部署产生命名冲突如 409 Conflict应将模块的关键命名输入如数据库/密钥模块的name、Cloud Run 模块的service_name暴露为variables.tf变量并在terraform.tfvars中附加 5 位随机字母数字后缀如webapp-db-a1b2c、webapp-frontend-x7y9z绝不硬编码在 module 块内部。5.3 保存配置文件创建本次执行/会话专属的工作区 scratch 目录例如scratch/tf_validate_{session_id}/用会话、对话或唯一运行 ID 命名避免并发执行互相覆盖将生成的 HCL 拆分写入providers.tfprovider 与 terraform 块main.tfmodule 与 resource 声明variables.tf变量声明terraform.tfvars变量值outputs.tf输出声明。生成器指令同样规定用variable块参数化环境特定值project ID、region、资源名并在terraform.tfvars中提供默认值同时要求用output块暴露关键引用端点、连接名。5.4 语义架构校验强制在运行任何 CLI 校验之前必须阅读 terraform_validator_instructions.md执行全面的语义审计确保配置符合校验器准则模块优先于资源、无自定义变量、GitHub source 格式正确等。校验器断言的关键点摘自 validator 指令强制模块优先关键凡可映射到已批准模块的 resource 块都要标记出来静态配置检查不得声明locals、for_each、count鼓励可配置变量project ID、region、资源名等必须参数化为variables.tf中的variable块检查模块间输出绑定数据库连接串、网络标识符子网、VPC 名、密钥/端点必须通过其他模块的输出绑定传入例外仅有default之类的既有默认配置强制固定版本关键每个含 Git/GitHub source 的模块块都必须带?ref...参数且 tag 必须与注册表对应组件修订的refTag完全一致无版本的 Git source 视为关键校验失败。5.5 执行本地 CLI 校验关键步骤初始化目录——直接使用 Terraform CLI 拉取 CFT 源码与下载 provider 插件terraform -chdirscratch/tf_validate_{session_id}/ init校验 HCL 块结构与类型连接terraform -chdirscratch/tf_validate_{session_id}/ validate干跑资源变更并验证配置可行性terraform -chdirscratch/tf_validate_{session_id}/ plan修复循环若 Terraform CLI 在初始化、校验或规划阶段报告错误或警告修正main.tf后重复执行上述检查命令直到全部干净通过。修复后还需执行生成器指令中的最终架构复查链路完整性审计所有模块/资源接口映射是否连通与约束完整性审计模块优先、直接资源仅用于无合适模块的场景。六、Phase 4语义审查与交接Semantic Review Handover最终模块化代码必须干净、健壮且安全地接线。6.1 语义审查与目标对齐对照用户意图与架构约束审计已通过校验的配置。若架构未达成目标或需调整回退到 Phase 2高层架构规划重新规划并重新生成。6.2 交付架构论证报告输出清晰、完整的最终报告说明高层架构布局High-Level Architecture Layout清晰概述每个模块或资源块及其在 GCP 基础设施中的结构角色架构论证Architectural Rationale明确解释为何选择特定的计算系统、边界与数据库模型若创建了直接资源而非模块说明其必要性若在多个产品间权衡给出选型理由模块间拓扑与数据流Inter-Module Topology Dataflow以描述性文本走查数据如何在 VPC 网络边界、计算块与依赖数据库组件之间流动。6.3 输出完整 Terraform 代码读取目标校验目录中生成的每个文件含.tf与.tfvars在最终响应中原样输出完整 HCL 配置。每个文件必须按以下格式呈现File:path[content]必须输出所有最终通过校验文件的完整、精确内容。校验器指令为这次交接设定了最终验收标准若所有校验通过且配置匹配设计目标用例则输出恰好LGTM。七、从设计到部署与主技能的衔接design指南输出的是一份经本地校验的模块化 HCL其下一步在 SKILL.md 主流程中继续推进。了解衔接点有助于理解本指南的定位与产物边界导出计划为 JSON强制在 scratch 目录运行terraform plan -outtfplan terraform show -json tfplan tfplan.json得到供 ADC 计划评估 API 使用的 JSON 计划Shifted-Left 最佳实践评估用gcloud design-center spaces generate-terraform-assessment-report space_id --locationlocation --projectproject_id --terraform-planscratch_directory_path/tfplan.json --formatjson在导入云端注册表前先做安全/成本/可靠性基准校验违规项回本地 HCL 修复后重跑校验迭代上限 3 次导入 ADC 模板注意 ADC 解析器的严格约束——禁止任何resource块仅允许module、variable、output、provider、禁止布尔隐式类型转换子网私有访问必须写成字符串subnet_private_access true、禁止terraform {}版本约束块部署与排障通过application_design_center:manage_applicationMCP 工具部署LRO 轮询每 30–60 秒一次失败时回退到 troubleshooting_guide.md 按 Case AADC 应用部署或 Case B原生 Terraform 部署定位问题修复一律在本地 HCL 完成并重新走校验→导入→部署循环上限 5 次。八、常见误区与最佳实践小结基于本指南的四阶段约束与同目录配套指令generator_instructions.md、planner_instructions.md、terraform_validator_instructions.md以下是实操中需要重点避免的误区误区正确做法模块source用 Terraform Registry 格式一律使用github.com/repo//dir?refrefTag固定版本格式source不带?ref版本参数tag 必须与注册表gitSource.refTag完全一致否则校验失败在 HCL/tfvars 中写明文口令、API Key全部接入 Secret Manager 模块并动态引用生成backend gcs {}远程状态块校验期间保持本地状态远程状态由 ADC 编排器管理模块间连接硬编码手写子网名、连接串一律通过module.exporter.output输出绑定滥用for_each、count、locals与三元逻辑保持扁平声明式仅module/resource/variable/output/provider模块命名用固定静态名用变量 5 位随机字母数字后缀如webapp-db-a1b2c避免 409 冲突传入完整资源名路径projects/...给 MCP 工具只传短模块 ID资源名最后一段如cloud-run-job九、总结本指南描述的design技能将 ADC 基础设施设计从黑盒自动生成转变为Agent 可控的设计与校验闭环以目录查询获取可信组件与精确版本以架构规划与模块输出绑定保证拓扑连通以terraform init/validate/plan本地循环保证语法与语义正确以语义审查与LGTM验收保证最终交接质量并以目标未达成即回退 Phase 2的反馈回路确保设计与意图对齐。配合 list_terraform_templates.py 与 fetch_terraform_template.py 两个本地 CLI 辅助脚本其行为由 list_terraform_templates_test.py 与 fetch_terraform_template_test.py 验证开发者可以完整复现查询模板 → 拉取基线 → 规划 → 生成 → 校验 → 交接的模块化设计流水线为后续导入 ADC 注册表与云端部署打下坚实基础。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 Application Design Center 的模块化 GCP Terraform 架构设计指南：四阶段 Agentic 设计管线实战
基于 Application Design Center 的模块化 GCP Terraform 架构设计指南四阶段 Agentic 设计管线实战【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文是 design_guide.md 的完整展开围绕 GCP Application Design CenterADC框架下的简化模块化 Terraform 架构设计技能Simplified GCP Modular Terraform Architect Skill展开。该技能以 Agent 自主执行的四阶段生成管线为核心意图摄取与目录查询 → 高层架构规划 → 模块优先生成与 CLI 校验 → 语义审查与交接将设计 → 校验 → 修正闭环固化到生成流程中。读完本文你将掌握如何在 ADC 中查询私有/公共目录组件、提取组件 gitSource 元数据构造固定版本的模块 source、规划模块间输出绑定、运行terraform init/validate/plan本地校验循环以及最终输出经语义审查的完整 HCL 交接产物。一、技能定位与整体工作流该 skill 处理的是GCP 云架构设计与本地校验适用于以下场景来自 SKILL.md 中design技能的描述设计模块化 Terraform 架构编写本地 HCL 代码通过terraform validate校验 HCL通过terraform plan规划 HCL以及后续向 ADC 注册表导入模板、部署与排障由同目录的部署类引用文档承接。它不适用于模板部署、计划评估或部署失败排障——这些属于application-design-center-design-deploy主技能的后续阶段。本文聚焦于其内部引用的design设计指南即 design_guide.md。整条设计管线是一个带反馈回路的四阶段流程四个阶段必须严格按顺序执行不可跳过当阶段 4 的语义审查判定配置未能完全满足用户的架构目标或意图时必须回退到阶段 2 重新规划并重新生成。二、三条强制架构约束贯穿全程的底线所有生成的配置在追求模块化结构的同时必须遵守以下命名与 HCL 风格约束默认网络与子网除非另有指定目标project_id中应使用预先存在的、均名为default的 VPC 网络和子网。密钥安全策略强制绝不允许在 HCL 代码或terraform.tfvars中写入明文密码、API Key 或凭据。所有密钥必须通过terraform-google-secret-manager模块声明为 GCP Secret Manager 资源并由目标服务动态引用。状态隔离策略强制校验期间将 Terraform 状态保持在 scratch 文件夹的本地状态。绝不生成远程 backend 块如backend gcs {}远程状态由上层编排器/部署注册表动态管理。这三条约束在主技能 SKILL.md 的阶段 1 交接核验中再次被强调在进入后续流程前必须逐行检查 HCL确认无明文凭据、无远程 backend 块一旦发现违规必须就地修正并重新校验。三、Phase 1意图摄取与目录查询Ingest Intent Catalog Query3.1 加载输入摄取用户的目标与指令作为后续所有阶段的决策基础。3.2 查询目录注册表私有 公共为补充设计信息需要通过原生manage_catalogMCP 工具、以CATALOG_OPERATION_LIST_COMPONENTS操作同时检索项目的自定义私有目录与 Google 公共目录。查询私有目录目标空间ServerNameapplication_design_centerToolNamemanage_catalogArguments{ project: project_id, location: location, spaceId: space_id, operation: CATALOG_OPERATION_LIST_COMPONENTS }查询公共 Google 目录ServerNameapplication_design_centerToolNamemanage_catalogArguments{ project: gcpdesigncenter, location: us-central1, spaceId: googlespace, catalogId: googlecatalog, operation: CATALOG_OPERATION_LIST_COMPONENTS }优先级规则必须优先使用目标空间中的私有目录模板而非公共 Google 模板以确保项目级定制被尊重。3.3 获取模块详情调用原生manage_catalogMCP 工具通过CATALOG_OPERATION_GET_COMPONENT_METADATA操作获取包含 inputs、outputs 与依赖关系的模块详细元数据或使用CATALOG_OPERATION_GET_COMPONENT_IAC直接获取底层 Terraform 源码{ project: project_id, location: location, spaceId: space_id, catalogTemplateId: short_module_id, catalogTemplateRevisionId: revision_id, operation: CATALOG_OPERATION_GET_COMPONENT_METADATA }约束只传短模块 ID例如cloud-run-job即完整资源名的最后一段不要传 list 命令返回的完整资源名路径。3.4 提取 gitSource 并构造固定版本的 source重要为了让本地 HCL 声明与 Design Center 注册表校验的版本约束完全一致必须从注册表提取精确的 Git 仓库 tag并用于 HCL 模块的source字段gitSource元数据块包含refTag、repo、dir会直接返回在manage_catalogMCP 工具的输出中位于gitSource字段下。如需回退到 CLI 描述修订详情可直接用 MCP 工具返回的修订 URI 执行describe命令gcloud design-center spaces catalogs templates revisions describe revision_uri具体两步操作提取gitSource块中的字段gitSource: dir: modules/v2 refTag: v0.33.0 repo: GoogleCloudPlatform/terraform-google-cloud-run按github.com/repo//dir?refrefTag模式构造 HCLsourceURIsource github.com/GoogleCloudPlatform/terraform-google-cloud-run//modules/v2?refv0.33.0这条规则与生成器指令中的Mandatory Version Pinning强制版本固定完全呼应——generator_instructions.md 明确要求所有模块source必须使用 Git/GitHub 仓库路径去掉https://前缀的github.com/...而非 Terraform Registry 格式且必须携带与注册表refTag完全一致的?refvX.Y.Z参数禁止无版本路径。四、Phase 2高层架构规划High-Level Architecture Planning4.1 强制资源初始化在制定任何方案之前必须先阅读 planner_instructions.md 中的指令确保其进入活动上下文后方可继续。从源码角度该文档定义的 Planner 角色是企业级 GCP 解决方案架构师其核心规划循环为三步查询注册表与架构 → 转换为 TF 模块/资源信息 → 生成模块优先的 HCL。这与 design_guide 的阶段 2 职责完全一致。4.2 设计高层架构基于阶段 1 识别出的模块规划连接关键模块化构建块VPC、Compute、Databases、Security的设计拓扑。4.3 制定集成模式决策确定核心模式布局决策例如 GKE 与 Cloud Run 的计算模型选型、存储引擎、网络边界、私有互联、数据库托管结构并基于可用模块落地。遵循 Google 最佳实践例如始终使用 Secret Manager 存储和引用数据库凭据而不是把口令作为输入参数传入私有连接优先使用 Private Service Connect 而非公共访问。4.4 盘点可复用的既有 TF 模块检查目录中是否已有可复用的 TF 模块以理解可用的构建块从而拼出匹配用户意图的端到端方案。目录包含 GCP 发布的公共目录与客户自有的私有目录当公共与私有目录出现重复模块时始终优先选择私有目录组件/模块。通过manage_catalogMCP 工具的CATALOG_OPERATION_GET_COMPONENT_METADATA操作核验所选模块的 inputs、outputs、必填项与引用输出{ project: gcpdesigncenter, location: us-central1, spaceId: googlespace, catalogId: googlecatalog, operation: CATALOG_OPERATION_GET_COMPONENT_METADATA, catalogTemplateId: module_id }约束使用短模块 ID资源名的最后一段例如cloud-run-job而非以projects/...开头的完整资源路径。若查询私有目录相应更新project、spaceId与catalogId参数。4.5 审查端到端解决方案模板审查 GCP 发布的最佳架构解决方案以及客户组织自己发布的解决方案将其作为可参考的参考架构。要探索可用模板可运行本地 CLI 脚本list_terraform_templates查看是否存在可作设计基线的既有应用模板。必须传入目标项目 ID 与空间 ID以同时检索公共 Google 模板与私有模板python3 scripts/list_terraform_templates.py --projectproject_id --space_idspace_id --catalog_idcatalog_id从源码看该脚本list_terraform_templates.py的执行逻辑恰好印证了文档的优先级规则它先查询私有目录default-catalog为默认 catalog再查询 Google 公共目录固定为gcpdesigncenter/us-central1/googlespace/googlecatalog并通过seen_template_ids去重——私有模板先处理因此天然排在返回列表前面且仅保留templateCategory APPLICATION_TEMPLATE的条目最终为每个条目标注source: private或source: google。优先级规则返回列表中私有应用模板排在最前标记为source: private。若存在合适的私有模板必须优先于标记为source: google的公共 Google 模板使用。4.6 获取 Terraform 模板运行本地 CLI 脚本fetch_terraform_template将基线模板配置拉取到本地工作区。必须传入目标项目 ID 与空间 IDpython3 scripts/fetch_terraform_template.py template_id --projectproject_id --space_idspace_id --out_dirtarget_directory_path输出目录不存在时会自动创建。从源码看该脚本fetch_terraform_template.py的完整链路为解析输入支持projects/...完整资源路径或短 ID→gcloud alpha design-center ... templates describe获取latestRevisionId→ 描述修订获取applicationTemplateRevisionSource→gcloud alpha design-center ... revisions generate生成 IaC 并返回 GCS URI →gcloud storage cp下载到本地临时目录 → 根据是否指定--out_dir决定落盘或直接打印全部 HCL 内容到 stdout每个文件以# 文件名 分隔。它的参数解析测试fetch_terraform_template_test.py覆盖了短 ID 默认解析到公共目录、以及完整路径解析两种情形验证了两种输入模式的行为。4.7 复核规划原则交叉核对 planner_instructions.md 中的规划指令。该文档还强调了规划阶段的关键动作将匹配到的模块视为基线优先用模块、仅在无对应模块时回退到直接资源通过CATALOG_OPERATION_GET_COMPONENT_METADATA核验模块输入输出预规划模块间 output-to-input 绑定禁止硬编码连接关系严格使用直接输出module.exporter_name.output_name并在生成文件前固化映射与拓扑决策。五、Phase 3模块优先生成与 CLI 校验循环Module-Only Generator CLI Validation Loop5.1 强制资源初始化在编写任何 HCL 之前必须阅读 generator_instructions.md 中的指令确保其进入活动上下文。5.2 生成原始 HCL编写标准 Terraform 代码尽可能优先使用 module 块仅在无合适模块时使用直接资源并遵循已加载指令中的规则。生成器指令细化了关键约束模块优先于直接资源直接resource块仅在无已批准模块可用、或作为模块化配置的必要补充时才允许禁止复杂 HCL 逻辑除非明确要求不要使用迭代语法for_each、count、三元条件逻辑或locals块保持结构扁平化与声明式必须包含标准terraform块声明hashicorp/google等必需 provider 及最低版本与provider google块默认目标项目与区域否则会破坏阶段 3 的密闭本地校验例程唯一模块实例命名关键为避免多实例部署或失败后重部署产生命名冲突如 409 Conflict应将模块的关键命名输入如数据库/密钥模块的name、Cloud Run 模块的service_name暴露为variables.tf变量并在terraform.tfvars中附加 5 位随机字母数字后缀如webapp-db-a1b2c、webapp-frontend-x7y9z绝不硬编码在 module 块内部。5.3 保存配置文件创建本次执行/会话专属的工作区 scratch 目录例如scratch/tf_validate_{session_id}/用会话、对话或唯一运行 ID 命名避免并发执行互相覆盖将生成的 HCL 拆分写入providers.tfprovider 与 terraform 块main.tfmodule 与 resource 声明variables.tf变量声明terraform.tfvars变量值outputs.tf输出声明。生成器指令同样规定用variable块参数化环境特定值project ID、region、资源名并在terraform.tfvars中提供默认值同时要求用output块暴露关键引用端点、连接名。5.4 语义架构校验强制在运行任何 CLI 校验之前必须阅读 terraform_validator_instructions.md执行全面的语义审计确保配置符合校验器准则模块优先于资源、无自定义变量、GitHub source 格式正确等。校验器断言的关键点摘自 validator 指令强制模块优先关键凡可映射到已批准模块的 resource 块都要标记出来静态配置检查不得声明locals、for_each、count鼓励可配置变量project ID、region、资源名等必须参数化为variables.tf中的variable块检查模块间输出绑定数据库连接串、网络标识符子网、VPC 名、密钥/端点必须通过其他模块的输出绑定传入例外仅有default之类的既有默认配置强制固定版本关键每个含 Git/GitHub source 的模块块都必须带?ref...参数且 tag 必须与注册表对应组件修订的refTag完全一致无版本的 Git source 视为关键校验失败。5.5 执行本地 CLI 校验关键步骤初始化目录——直接使用 Terraform CLI 拉取 CFT 源码与下载 provider 插件terraform -chdirscratch/tf_validate_{session_id}/ init校验 HCL 块结构与类型连接terraform -chdirscratch/tf_validate_{session_id}/ validate干跑资源变更并验证配置可行性terraform -chdirscratch/tf_validate_{session_id}/ plan修复循环若 Terraform CLI 在初始化、校验或规划阶段报告错误或警告修正main.tf后重复执行上述检查命令直到全部干净通过。修复后还需执行生成器指令中的最终架构复查链路完整性审计所有模块/资源接口映射是否连通与约束完整性审计模块优先、直接资源仅用于无合适模块的场景。六、Phase 4语义审查与交接Semantic Review Handover最终模块化代码必须干净、健壮且安全地接线。6.1 语义审查与目标对齐对照用户意图与架构约束审计已通过校验的配置。若架构未达成目标或需调整回退到 Phase 2高层架构规划重新规划并重新生成。6.2 交付架构论证报告输出清晰、完整的最终报告说明高层架构布局High-Level Architecture Layout清晰概述每个模块或资源块及其在 GCP 基础设施中的结构角色架构论证Architectural Rationale明确解释为何选择特定的计算系统、边界与数据库模型若创建了直接资源而非模块说明其必要性若在多个产品间权衡给出选型理由模块间拓扑与数据流Inter-Module Topology Dataflow以描述性文本走查数据如何在 VPC 网络边界、计算块与依赖数据库组件之间流动。6.3 输出完整 Terraform 代码读取目标校验目录中生成的每个文件含.tf与.tfvars在最终响应中原样输出完整 HCL 配置。每个文件必须按以下格式呈现File:path[content]必须输出所有最终通过校验文件的完整、精确内容。校验器指令为这次交接设定了最终验收标准若所有校验通过且配置匹配设计目标用例则输出恰好LGTM。七、从设计到部署与主技能的衔接design指南输出的是一份经本地校验的模块化 HCL其下一步在 SKILL.md 主流程中继续推进。了解衔接点有助于理解本指南的定位与产物边界导出计划为 JSON强制在 scratch 目录运行terraform plan -outtfplan terraform show -json tfplan tfplan.json得到供 ADC 计划评估 API 使用的 JSON 计划Shifted-Left 最佳实践评估用gcloud design-center spaces generate-terraform-assessment-report space_id --locationlocation --projectproject_id --terraform-planscratch_directory_path/tfplan.json --formatjson在导入云端注册表前先做安全/成本/可靠性基准校验违规项回本地 HCL 修复后重跑校验迭代上限 3 次导入 ADC 模板注意 ADC 解析器的严格约束——禁止任何resource块仅允许module、variable、output、provider、禁止布尔隐式类型转换子网私有访问必须写成字符串subnet_private_access true、禁止terraform {}版本约束块部署与排障通过application_design_center:manage_applicationMCP 工具部署LRO 轮询每 30–60 秒一次失败时回退到 troubleshooting_guide.md 按 Case AADC 应用部署或 Case B原生 Terraform 部署定位问题修复一律在本地 HCL 完成并重新走校验→导入→部署循环上限 5 次。八、常见误区与最佳实践小结基于本指南的四阶段约束与同目录配套指令generator_instructions.md、planner_instructions.md、terraform_validator_instructions.md以下是实操中需要重点避免的误区误区正确做法模块source用 Terraform Registry 格式一律使用github.com/repo//dir?refrefTag固定版本格式source不带?ref版本参数tag 必须与注册表gitSource.refTag完全一致否则校验失败在 HCL/tfvars 中写明文口令、API Key全部接入 Secret Manager 模块并动态引用生成backend gcs {}远程状态块校验期间保持本地状态远程状态由 ADC 编排器管理模块间连接硬编码手写子网名、连接串一律通过module.exporter.output输出绑定滥用for_each、count、locals与三元逻辑保持扁平声明式仅module/resource/variable/output/provider模块命名用固定静态名用变量 5 位随机字母数字后缀如webapp-db-a1b2c避免 409 冲突传入完整资源名路径projects/...给 MCP 工具只传短模块 ID资源名最后一段如cloud-run-job九、总结本指南描述的design技能将 ADC 基础设施设计从黑盒自动生成转变为Agent 可控的设计与校验闭环以目录查询获取可信组件与精确版本以架构规划与模块输出绑定保证拓扑连通以terraform init/validate/plan本地循环保证语法与语义正确以语义审查与LGTM验收保证最终交接质量并以目标未达成即回退 Phase 2的反馈回路确保设计与意图对齐。配合 list_terraform_templates.py 与 fetch_terraform_template.py 两个本地 CLI 辅助脚本其行为由 list_terraform_templates_test.py 与 fetch_terraform_template_test.py 验证开发者可以完整复现查询模板 → 拉取基线 → 规划 → 生成 → 校验 → 交接的模块化设计流水线为后续导入 ADC 注册表与云端部署打下坚实基础。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考