配置管理边界

本文档介绍了如何使用 Resource Manager 设置和管理管理边界和功能配置。管理边界可为 Agent Registry 实现跨项目资源发现和治理。

准备工作

在配置边界和功能配置之前，请获取所需角色并启用所需 API。

所需的角色

如需获得配置边界和功能所需的权限，请让您的管理员为您授予以下 IAM 角色：

  • 创建、更新和删除边界和功能配置：目标文件夹或组织（以及管理项目，如果您提供用户管理的管理项目）的 Resource Manager Editor (roles/resourcemanager.editor)
  • 查看边界和功能配置：目标文件夹或组织的 Resource Manager Viewer (roles/resourcemanager.viewer)
  • 将标记附加到成员项目：
    • 目标文件夹、组织或成员项目的 Tag User (roles/resourcemanager.tagUser)
    • 目标文件夹或组织的 Tag Administrator (roles/resourcemanager.tagAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用 API

  • 如需启用 Resource Manager API，请使用 gcloud services enable 命令：

    gcloud services enable cloudresourcemanager.googleapis.com \
  --project=PROJECT_ID

    将 PROJECT_ID 替换为您的项目 ID。

设置管理边界

您可以通过以下两种方式之一在文件夹或组织上设置管理边界：

  • 文件夹级或组织级边界（无标记过滤条件）：包含文件夹或组织中的所有下级项目。跳过第 1 步和第 4 步，仅完成第 2 步：创建边界（不含 --tag-key 和 --tag-value）和第 3 步：创建功能配置。
  • 基于标记的边界：按标记值对文件夹或组织中的项目进行分区。完成以下所有四个步骤。

第 1 步：配置分区标记键

如果您要创建不含标记过滤条件的文件夹级或组织级边界，请跳过此步骤。默认情况下，BoundaryConfig 资源未配置任何标记键。

对于基于标记的边界，BoundaryConfig 资源会建立用于对文件夹或组织中的项目进行分区的标记键。请先配置此资源，然后再创建基于标记的边界。

如需设置分区标记键，请使用 gcloud resource-manager boundary-configs update 命令：

gcloud resource-manager boundary-configs update \
  --folder=FOLDER_ID \
  --tag-key=TAG_KEY_NAME

如需在组织上配置标记键，请指定 --organization=ORGANIZATION_ID，而不是 --folder。如果您之前配置了标记键，并希望切换到未标记的边界（当父级下不存在边界时），请使用 --clear-tag-key（而非 --tag-key）运行此命令。

替换以下内容：

  • FOLDER_ID：父级文件夹的 ID
  • TAG_KEY_NAME：标记键的名称，格式为 ORGANIZATION_ID/TAG_KEY_SHORT_NAME，例如 123456789012/env

第 2 步：创建边界

在文件夹或组织中创建 Boundary 资源。

如需创建不含标记过滤条件的文件夹级边界（该边界会自动包含文件夹中的所有后代项目），请使用不含 --tag-key 和 --tag-value 的 gcloud resource-manager boundaries create 命令：

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary"

如需在第 1 步中配置分区标记键后创建基于标记的边界，请添加 --tag-key 和 --tag-value 标志：

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary" \
  --tag-key=TAG_KEY_NAME \
  --tag-value=TAG_VALUE_SHORT_NAME

如需在组织中创建边界，请指定 --organization=ORGANIZATION_ID，而不是 --folder。

替换以下内容：

  • BOUNDARY_ID：边界的唯一 ID，例如 prod-boundary
  • FOLDER_ID：父级文件夹的 ID
  • TAG_KEY_NAME：您配置的标记键，例如 123456789012/env
  • TAG_VALUE_SHORT_NAME：项目必须具有的标记值才能加入边界，例如 prod

第 3 步：创建功能配置

创建 CapabilityConfig 资源，将边界关联到管理项目，并声明哪些服务跨边界进行管理。

如需创建功能配置，请使用 gcloud resource-manager capability-configs create 命令，并为智能体注册表指定 --types=agent-management：

gcloud resource-manager capability-configs create \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --types=agent-management \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID \
  --display-name="DISPLAY_NAME"

如需在组织中创建功能配置，请指定 --organization=ORGANIZATION_ID，而不是 --folder。

替换以下内容：

  • CAPABILITY_CONFIG_ID：功能配置的唯一 ID，例如 prod-capabilities
  • FOLDER_ID：父级文件夹的 ID
  • BOUNDARY_ID：您创建的边界的 ID
  • DISPLAY_NAME：人类可读的显示名称

如需在没有边界的单个独立项目上启用功能，请跳过第 1、2 和 4 步，然后使用 --project=PROJECT_NUMBER 和 --management-project=projects/PROJECT_NUMBER（而不是 --folder 和 --boundaries）运行此命令。

如需将现有项目用作管理项目，请传递 --management-project=projects/PROJECT_NUMBER 标志。您指定的项目必须满足以下要求，否则命令会失败并报错：

  • 与 CapabilityConfig 资源位于同一父级（folders/FOLDER_ID 或 organizations/ORGANIZATION_ID）下。
  • 处于 ACTIVE 生命周期状态。
  • 尚未指定为管理项目。

如果您省略 --management-project，Resource Manager 会自动在父级文件夹或组织下直接预配专用管理项目。

创建 CapabilityConfig 资源会自动在管理项目上启用相应的服务 API（例如，在指定 agent-management 时启用 agentregistry.googleapis.com）。您无需在管理项目上手动启用这些 API。

第 4 步：将标记附加到成员项目

如果您创建了不含标记过滤条件的文件夹级或组织级边界，请跳过此步骤，因为所有后代项目都会自动包含在内。

对于基于标记的边界，当您将匹配的标记值绑定到项目时，项目会动态加入管理边界。

如需将标记附加到边界内的每个项目，请使用 gcloud resource-manager tags bindings create 命令：

gcloud resource-manager tags bindings create \
  --tag-value=TAG_VALUE_NAME \
  --parent=//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER

替换以下内容：

  • TAG_VALUE_NAME：标记值名称，例如 123456789012/env/prod
  • PROJECT_NUMBER：要包含在边界中的项目的项目编号（或项目 ID）

管理功能配置

您可以列出、描述、更新和删除功能配置。本部分中的示例使用 --folder=FOLDER_ID。如需管理组织或项目的功能配置，请指定 --organization=ORGANIZATION_ID 或 --project=PROJECT_NUMBER，而不是 --folder（边界只能附加到文件夹级或组织级功能配置）。

列出功能配置

如需列出文件夹中的所有功能配置，请使用 gcloud resource-manager capability-configs list 命令：

gcloud resource-manager capability-configs list \
  --folder=FOLDER_ID

描述功能配置

如需查看配置详情和分配的管理项目，请使用 gcloud resource-manager capability-configs describe 命令：

gcloud resource-manager capability-configs describe \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

更新关联的边界

如需更新与功能配置关联的边界，请使用 gcloud resource-manager capability-configs update 命令：

gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID_1,folders/FOLDER_ID/boundaries/BOUNDARY_ID_2

update 命令还接受 --types 和 --display-name 标志，以更新已启用的功能类型或显示名称。

删除功能配置

当 CapabilityConfig 资源附加了边界时，无法删除该资源；当 Boundary 资源附加到 CapabilityConfig 资源时，无法删除该资源。

如需在不再需要跨项目管理时删除功能配置，请执行以下操作：

  1. 如需分离关联的边界，请在 gcloud resource-manager capability-configs update 命令中使用 --clear-boundaries 标志：

    gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --clear-boundaries

  2. 如需删除功能配置，请使用 gcloud resource-manager capability-configs delete 命令：

    gcloud resource-manager capability-configs delete \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

后续步骤