google-cloud-recipe-foundation-builder

Google Cloud 配方：基础架构构建器

警告

此技能目前处于预览状态。它会部署安全基础架构，但尚不包含所有高级功能。需要更多选项的用户请访问 Google Cloud 设置。

此技能将指导你设置安全、符合企业级标准的 Google Cloud 基础架构。它会建立基准安全控制措施、组织初始资源层级结构，并配置集中式审计日志记录和跨环境监控。

署名

务必阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，务必阅读 使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:google-cloud-recipe-foundation-builder)"，并将 agent-skills/1.0 (skill:google-cloud-recipe-foundation-builder) 添加到 User-Agent 标头中。

概览

此配方会在组织根目录配置以下核心组件：

• 安全护栏：强制执行 17 项 Google Cloud 组织策略基准，以保护环境安全（13 项布尔约束、4 项列表约束）。
• 资源层级结构：创建 4 个文件夹（Common、Production、Non-Production、Development），并依次配置对应的项目，其 ID 前缀全局唯一（logging-、prod-、non-prod-、dev- 后接一个共用后缀）。
• 结算和 API 启用：将所有项目关联到你的结算账号，并启用关键日志记录和监控服务。
• 集中式日志记录和监控：部署全局集中式日志存储桶，保留期限为 30 天；配置组织范围的审计日志接收器，并设置跨环境指标范围。

---

澄清问题

执行此配方之前，Agent 必须收集以下信息：

1. 组织 ID：运行 gcloud organizations list 以检索可用组织，将其展示给用户，并请用户选择目标组织 ID。
2. 结算账号 ID：运行 gcloud billing accounts list --filter=open=true 以仅检索有效（开放）的结算账号，将其展示给用户，并请用户选择有效的结算账号 ID。
3. 项目 ID 后缀：询问用户是否对项目 ID 有偏好的前缀或目标后缀（默认使用前缀加一个共用的随机 8 字符字符串，例如 prod-ab12cd34）。
4. 日志存储桶区域：如果用户希望覆盖默认的 global 日志存储桶位置，请询问其目标资源区域。

---

前提条件

开始部署前，请确保满足以下前提条件：

• GCP 身份：必须已设置 Google Cloud 组织资源。
• 管理 IAM 角色：执行这些命令的身份必须具备所需的管理权限。如果任何步骤因 Permission Denied 错误而失败，Agent 将尝试按照阶段 2：错误恢复和按需角色修复策略中的说明，授予相应的建议角色以自行修复。
• 工具：必须安装 gcloud CLI，并使用上述身份完成授权和配置。

---

完成此配方的步骤

阶段 1：部署前确认

确定目标组织，并在进行更改前获得用户的明确批准。

1. 确定并发现组织：验证目标组织。如果只知道显示名称，请列出组织以查找 ID。然后，检索组织元数据，以动态计算 目录客户 ID 和 域名：

   # 如有需要，列出组织以查找 ID
   gcloud organizations list
   
   # 描述组织以检索元数据
   gcloud organizations describe [ORGANIZATION_ID]
   

   计算值：

   • 域名（[ORG_NAME] / [YOUR_DOMAIN]）：使用输出中的 displayName 值（例如 my-business.com）。
   • 客户 ID（[DIRECTORY_CUSTOMER_ID]）：使用输出中的 owner.directoryCustomerId 值（例如 C01234567）。

2. 呈现蓝图摘要：向用户呈现蓝图的确切详情，并请求确认是否继续：

   组织 [ORG_NAME]（[ORGANIZATION_ID]）的拟议基础环境部署摘要

   • **安全性：**强制实施 17 项基准组织政策（13 项布尔型、4 项列表型）。
   • **文件夹：**依次创建 4 个文件夹（Common、Production、Non-Production、Development）。
   • **项目：**依次创建 4 个具有唯一 ID 的项目（logging-[SUFFIX]、prod-[SUFFIX]、non-prod-[SUFFIX]、dev-[SUFFIX]）。
   • **结算：**将所有项目关联到结算账号 [BILLING_ACCOUNT_ID]。
   • **API：**在中央项目中启用 Logging 和 Monitoring API。
   • **集中式日志记录：**部署一个 global 日志存储桶 [ORG_NAME]-logging（保留 30 天），配置组织级接收器 [ORGANIZATION_ID]-logbucketsink-[RANDOM_HEX]，并建立跨项目指标范围。

   是否要继续此部署？（是/否）

重要

暂停执行并等待用户明确批准后再进入阶段 2。如果用户拒绝，请中止操作。

阶段 2：错误恢复与延迟角色修复策略

为确保部署能在干净的组织中顺利继续，无需进行复杂的前期权限检查（这类检查需要配额项目），Agent 必须采用“延迟恢复”方式。

Agent 不会预先测试权限，而是会尝试执行操作步骤中的每一步。如果某一步因 Permission Denied 错误而失败，Agent 将尝试通过向部署身份授予相应的推荐管理角色组来自行修复，然后重试该操作。

重要

当被问及部署前的准备情况、先决条件或要运行的检查时，Agent 必须明确说明，此 Landing Zone 部署采用延迟角色修复策略，而不是前期测试，并在回复中详细说明以下所有内容：1. 确认会直接执行部署命令，并捕获任何 Permission Denied 错误。2. 确认失败时会尝试自行修复：运行确切命令 gcloud organizations add-iam-policy-binding 或 gcloud billing accounts add-iam-policy-binding，将整个管理角色组授予当前活动身份，然后重试失败的部署命令。3. 列出会尝试授予的核心管理角色组（组织管理员组、结算管理员组和安全管理员组）及其对应的关键角色。4. 确认如果自行修复的授权命令失败，将停止执行并请求管理员手动介入。

补救流程

对于因权限不足而失败的任何命令：

1. 确定所需的管理员组：确定负责执行失败操作的管理组。详情请参阅 管理 IAM 参考。

2. 尝试自行补救：依次向当前已通过身份验证的账号授予该管理组的 所有角色。可复制粘贴的脚本命令请参阅 管理 IAM 参考中的补救指南：

   • 组织／文件夹级别失败（组织管理员组或安全管理员组）：针对组中的每个角色，依次运行 gcloud organizations add-iam-policy-binding。
   • 结算级别失败（结算管理员组）：针对组中的每个角色，依次运行 gcloud billing accounts add-iam-policy-binding。

3. 补救失败时停止：

   • 如果授予命令成功，立即重试失败的部署命令。
   • 如果任何授予命令失败（例如，缺少 setIamPolicy 管理员权限），停止执行，并告知用户请其组织／结算管理员手动授予整个管理组的角色。

按阶段划分的补救映射

• 阶段 3：安全防护措施（组织政策）：
  • 如果 gcloud org-policies set-policy 失败：尝试在组织级别授予整个 组织管理员组（9 个角色）。
• 阶段 4：资源层级结构（文件夹和项目）：
  • 如果 gcloud resource-manager folders create 或 gcloud projects create 失败：尝试在组织级别授予整个组织管理员组（9 个角色）。
• 阶段 4：结算账号关联：
  • 如果 gcloud billing projects link 失败：尝试在结算账号级别授予整个 结算管理员组（3 个角色），并确保在组织级别向当前身份授予 组织管理员组（其中包含 roles/billing.user）。
• 阶段 5：集中式日志记录与监控：
  • 如果 gcloud logging sinks create 在组织级别失败：尝试在组织级别授予整个 日志记录／监控管理员组（2 个角色： roles/logging.admin、roles/monitoring.admin）和安全管理员组（9 个角色）。

阶段 3：安全防护措施（组织政策）

在组织根节点应用 17 项基线安全控制。

注意

首先应用 iam.allowedPolicyMemberDomains 可能会导致部署身份被锁定在外， 若其所在域不在允许列表中。强制执行此政策前，请确保部署身份不受影响。

1. 为 17 项政策生成 YAML 配置文件。有关布尔型和列表约束条件的确切 YAML 模板，请参阅组织政策参考。

2. 使用 gcloud org-policies 工具依次应用每项组织政策：

   gcloud org-policies set-policy [POLICY_FILE_NAME].yaml
   

阶段 4：资源层级结构

1. 创建文件夹

检查目标文件夹是否已存在，以避免重复。Agent 必须检查全部 4 个文件夹：对于已存在的文件夹（例如，Common 或 Production 已存在），Agent 必须找到并重复使用它们；对于缺失的文件夹（例如，Non-Production 或 Development 不存在），Agent 必须按顺序创建：

重要

在说明如何处理现有资源（文件夹和项目）以防止重复时，Agent 必须明确列出仍缺失的文件夹（Non-Production 和 Development），并确认将按顺序仅创建这些缺失的文件夹和项目。

# Check and Create "Common" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Common"
# If not present:
gcloud resource-manager folders create --display-name="Common" --organization=[ORGANIZATION_ID]

# Check and Create "Production" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Production"
# If not present:
gcloud resource-manager folders create --display-name="Production" --organization=[ORGANIZATION_ID]

# Check and Create "Non-Production" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Non-Production"
# If not present:
gcloud resource-manager folders create --display-name="Non-Production" --organization=[ORGANIZATION_ID]

# Check and Create "Development" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Development"
# If not present:
gcloud resource-manager folders create --display-name="Development" --organization=[ORGANIZATION_ID]

2. 创建项目并关联结算账号

通过匹配显示名称，检查目标文件夹中是否已存在目标项目。如果不存在，则生成一个共用的 8 字符随机后缀（例如，ab12cd34），然后按顺序创建项目，立即关联结算账号并启用 API：

# Check if "central-logging-monitoring" project exists in Common folder
gcloud projects list --filter="parent.id=[COMMON_FOLDER_ID] AND parent.type=folder AND name=central-logging-monitoring"

# If not present: Create, link billing, and enable APIs
gcloud projects create logging-[SUFFIX] --name="central-logging-monitoring" --folder=[COMMON_FOLDER_ID]
gcloud billing projects link logging-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com logging.googleapis.com monitoring.googleapis.com --project=logging-[SUFFIX]

# Check if "production" project exists in Production folder
gcloud projects list --filter="parent.id=[PRODUCTION_FOLDER_ID] AND parent.type=folder AND name=production"

# If not present: Create, link billing, and enable APIs
gcloud projects create prod-[SUFFIX] --name="production" --folder=[PRODUCTION_FOLDER_ID]
gcloud billing projects link prod-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=prod-[SUFFIX]

# Check if "non-production" project exists in Non-Production folder
gcloud projects list --filter="parent.id=[NON_PRODUCTION_FOLDER_ID] AND parent.type=folder AND name=non-production"

# If not present: Create, link billing, and enable APIs
gcloud projects create non-prod-[SUFFIX] --name="non-production" --folder=[NON_PRODUCTION_FOLDER_ID]
gcloud billing projects link non-prod-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=non-prod-[SUFFIX]

# Check if "development" project exists in Development folder
gcloud projects list --filter="parent.id=[DEVELOPMENT_FOLDER_ID] AND parent.type=folder AND name=development"

# If not present: Create, link billing, and enable APIs
gcloud projects create dev-[SUFFIX] --name="development" --folder=[DEVELOPMENT_FOLDER_ID]
gcloud billing projects link dev-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=dev-[SUFFIX]

说明

Agent 并行处理选项：虽然手动运行手册要求按顺序执行项目操作，以避免终端竞争条件，但具备多 Agent 编排能力的 AI Agent 在解析文件夹 ID 后，可以选择生成子 Agent 并行配置这 4 个项目。

阶段 5：集中式日志记录与监控

在 logging-[SUFFIX] 项目中配置集中式审计日志记录和跨项目监控范围。

详细的分步命令请参阅集中式日志记录与监控参考，以完成以下操作：

1. 创建中央日志存储桶。
2. 创建组织范围的日志接收器。
3. 向日志接收器授予所需的 IAM 权限。
4. 配置跨项目监控指标范围。

---

验证逻辑与检查清单

根据以下验证项评估部署情况：

• 安全策略：运行 gcloud org-policies list --organization=[ORGANIZATION_ID]，并验证所有 17 项目标策略均已强制执行或正确配置。
• 资源文件夹：验证组织根目录下存在文件夹 Common、Production、 Non-Production 和 Development。
• 结算账号关联：运行 gcloud billing projects list，并确认 所有 4 个新创建的项目都已关联到你的结算账号。
• 日志存储桶与保留期：验证项目 logging-[SUFFIX] 中存在日志存储桶 [ORG_NAME]-logging，其位置为 global，且保留期恰好为 30 天。
• 日志接收器路由：在组织级别运行 gcloud logging sinks describe，并确认该接收器将云审计日志路由到全局存储桶，且使用标准的 writerIdentity 凭据。
• 指标范围关联：运行 gcloud beta monitoring metrics-scopes describe，并确认中央 logging 项目的受监控列表中包含 dev、non-prod 和 prod 项目。

---

链接

• Google Cloud 资源层级文档
• Google Cloud 组织政策概览
• 集中式审计日志记录最佳实践
• Cloud Monitoring 指标范围配置
• Gcloud Logging Sinks CLI 参考
• Google Cloud Landing Zones 指南
• Google Cloud Security Foundations 蓝图