企业官网建设流程全解析

基于 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 Center（ADC）框架下的"简化模块化 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 风格约束：

1. 默认网络与子网：除非另有指定，目标<project_id>中应使用预先存在的、均名为"default"的 VPC 网络和子网。
2. 密钥安全策略（强制）：绝不允许在 HCL 代码或terraform.tfvars中写入明文密码、API Key 或凭据。所有密钥必须通过terraform-google-secret-manager模块声明为 GCP Secret Manager 资源，并由目标服务动态引用。
3. 状态隔离策略（强制）：校验期间将 Terraform 状态保持在 scratch 文件夹的本地状态。绝不生成远程 backend 块（如backend "gcs" {}），远程状态由上层编排器/部署注册表动态管理。

这三条约束在主技能 SKILL.md 的阶段 1 交接核验中再次被强调：在进入后续流程前，必须逐行检查 HCL，确认无明文凭据、无远程 backend 块，一旦发现违规必须就地修正并重新校验。

三、Phase 1：意图摄取与目录查询（Ingest Intent & Catalog Query）

3.1 加载输入

摄取用户的目标与指令，作为后续所有阶段的决策基础。

3.2 查询目录注册表（私有 + 公共）

为补充设计信息，需要通过原生manage_catalogMCP 工具、以CATALOG_OPERATION_LIST_COMPONENTS操作同时检索项目的自定义私有目录与 Google 公共目录。

查询私有目录（目标空间）：

• ServerName：application_design_center
• ToolName：manage_catalog
• Arguments：

{ "project": "<project_id>", "location": "<location>", "spaceId": "<space_id>", "operation": "CATALOG_OPERATION_LIST_COMPONENTS" }

查询公共 Google 目录：

• ServerName：application_design_center
• ToolName：manage_catalog
• Arguments：

{ "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>

具体两步操作：

1. 提取gitSource块中的字段：

gitSource: dir: modules/v2 refTag: v0.33.0 repo: GoogleCloudPlatform/terraform-google-cloud-run

2. 按github.com/<repo>//<dir>?ref=<refTag>模式构造 HCLsourceURI：

source = "github.com/GoogleCloudPlatform/terraform-google-cloud-run//modules/v2?ref=v0.33.0"

这条规则与生成器指令中的Mandatory Version Pinning（强制版本固定）完全呼应——generator_instructions.md 明确要求所有模块source必须使用 Git/GitHub 仓库路径（去掉https://前缀的github.com/...）而非 Terraform Registry 格式，且必须携带与注册表refTag完全一致的?ref=vX.Y.Z参数，禁止无版本路径。

四、Phase 2：高层架构规划（High-Level Architecture Planning）

4.1 强制资源初始化

在制定任何方案之前，必须先阅读 planner_instructions.md 中的指令，确保其进入活动上下文后方可继续。

从源码角度，该文档定义的 Planner 角色是"企业级 GCP 解决方案架构师"，其核心规划循环为三步：查询注册表与架构 → 转换为 TF 模块/资源信息 → 生成模块优先的 HCL。这与 design_guide 的阶段 2 职责完全一致。

4.2 设计高层架构

基于阶段 1 识别出的模块，规划连接关键模块化构建块（VPC、Compute、Databases、Security）的设计拓扑。

4.3 制定集成模式决策

确定核心模式布局决策（例如 GKE 与 Cloud Run 的计算模型选型、存储引擎、网络边界、私有互联、数据库托管结构），并基于可用模块落地。遵循 Google 最佳实践，例如：

1. 始终使用 Secret Manager 存储和引用数据库凭据，而不是把口令作为输入参数传入；
2. 私有连接优先使用 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 --project="<project_id>" --space_id="<space_id>" --catalog_id="<catalog_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 与空间 ID：

python3 scripts/fetch_terraform_template.py <template_id> --project="<project_id>" --space_id="<space_id>" --out_dir="<target_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 Loop）

5.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.tf：provider 与 terraform 块；
• main.tf：module 与 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 -chdir=scratch/tf_validate_{session_id}/ init

校验 HCL 块结构与类型连接：

terraform -chdir=scratch/tf_validate_{session_id}/ validate

干跑资源变更并验证配置可行性：

terraform -chdir=scratch/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 主流程中继续推进。了解衔接点有助于理解本指南的定位与产物边界：

1. 导出计划为 JSON（强制）：在 scratch 目录运行terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json，得到供 ADC 计划评估 API 使用的 JSON 计划；
2. Shifted-Left 最佳实践评估：用gcloud design-center spaces generate-terraform-assessment-report <space_id> --location=<location> --project=<project_id> --terraform-plan="<scratch_directory_path>/tfplan.json" --format=json在导入云端注册表前先做安全/成本/可靠性基准校验，违规项回本地 HCL 修复后重跑校验（迭代上限 3 次）；
3. 导入 ADC 模板：注意 ADC 解析器的严格约束——禁止任何resource块（仅允许module、variable、output、provider）、禁止布尔隐式类型转换（子网私有访问必须写成字符串subnet_private_access = "true"）、禁止terraform {}版本约束块；
4. 部署与排障：通过application_design_center:manage_applicationMCP 工具部署，LRO 轮询每 30–60 秒一次，失败时回退到 troubleshooting_guide.md 按 Case A（ADC 应用部署）或 Case B（原生 Terraform 部署）定位问题，修复一律在本地 HCL 完成并重新走校验→导入→部署循环（上限 5 次）。

八、常见误区与最佳实践小结

基于本指南的四阶段约束与同目录配套指令（generator_instructions.md、planner_instructions.md、terraform_validator_instructions.md），以下是实操中需要重点避免的误区：

九、总结

本指南描述的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