管理对代理的 Google Cloud API 的访问权限

应用开发者可以为在 Google Kubernetes Engine (GKE) 上运行的 AI 智能体请求代理身份。代理身份是一种按 Pod 分配的身份，可以加密方式绑定到工作负载中的每个 Pod。然后，代理可以使用代理身份向 Google Cloud API 进行身份验证。您可以通过在 Identity and Access Management (IAM) 政策中将代理添加为主账号，来控制代理可以访问哪些资源。本文档介绍了如何管理对使用代理身份的代理的 Google Cloud API 和服务的访问权限。

本文档适用于安全管理员和平台管理员，他们负责管理开发者部署到 GKE 集群的代理的授权。您应该已经熟悉以下主题：

准备工作

在开始之前，请确保您已执行以下任务：

  • 启用 Google Kubernetes Engine API。
    • 启用 Google Kubernetes Engine API
  • 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。

所需的角色

如需获得管理代理对 Google Cloud API 的访问权限所需的权限，请让管理员为您授予 Google Cloud 项目的以下 IAM 角色：

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

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

查找代理的委托人标识符

本部分介绍了如何为代理构建主体标识符。 您可以在 IAM 政策中使用此标识符来控制代理可以访问哪些资源。

任何请求代理身份的代理工作负载都会获得一个对该工作负载而言唯一的 SPIFFE 身份字符串。当应用调用 Google Cloud API 时，系统会使用代理身份访问令牌对调用进行身份验证，以验证工作负载是否具有代理身份。此访问令牌包含代理工作负载的 IAM 主账号标识符，您可以将其纳入 IAM 政策中，以控制该代理有权访问哪些资源。

设计 IAM 政策时，您可以使用以下信息来构建代理的主账号标识符：

  • 项目的资源层次结构。
  • 集群名称。
  • Kubernetes 命名空间以及该命名空间中的 Kubernetes ServiceAccount。

当开发者部署的代理获得的代理身份与主账号标识符一致时，该代理会继承您在政策中指定的访问权限。

如需查找要在政策中使用的主账号标识符，请按以下步骤操作：

  1. 确定身份的信任域。信任域取决于项目是否属于组织，如下所示：

    • 组织中的项目：

      agents.global.org-ORGANIZATION_ID.system.id.goog

      将 ORGANIZATION_ID 替换为组织 ID。

    • 未纳入组织的项目：

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      将 PROJECT_NUMBER 替换为该集群项目的项目编号。

  2. 确定集群的以下信息：

    • GKE 集群的名称。
    • 集群控制平面的位置，例如 us-central1。
    • 开发者部署工作负载的 Kubernetes 命名空间。
    • 开发者必须用于代理工作负载的 Kubernetes ServiceAccount 的名称。

    如果您不知道此信息，请咨询您的平台团队。平台团队应在集群中设置命名空间、ServiceAccount 和 RBAC 政策，以便具有不同访问权限要求的代理获得不同的身份。

  3. 构建主账号标识符：

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

    替换以下内容：

    • TRUST_DOMAIN：代理身份的信任域。
    • PROJECT_NUMBER：集群项目的项目编号。
    • CONTROL_PLANE_LOCATION：集群控制平面所在的区域或可用区。
    • CLUSTER_NAME：集群的名称。
    • KUBERNETES_NAMESPACE：Kubernetes 命名空间的名称。
    • KUBERNETES_SERVICEACCOUNT：Kubernetes ServiceAccount 的名称。

使用政策控制访问权限

本部分介绍了如何使用代理的主账号标识符来控制代理可以访问哪些 Google Cloud API 和服务。如需控制访问权限，请在以下任一 IAM 政策中添加主账号标识符：

创建或更新政策后，任何请求代理身份并在该命名空间中运行且使用该 ServiceAccount 的代理都将拥有您在政策中指定的访问权限。

授权代理访问身份验证管理器

Agent Identity 身份验证管理器是一种身份验证代理和凭据保险库，代理可以使用它来获取凭据，以便以代理自己的身份或代表最终用户访问外部工具和服务。身份验证管理器可以有一个或多个身份验证提供程序，每个身份验证提供程序都负责处理特定服务的特定身份验证和凭据获取流程。如需向 GKE 代理授予对特定身份验证提供程序的访问权限，请按以下步骤操作：

  1. 查找代理的委托人标识符。
  2. 获取代理需要访问的身份验证提供方的名称。

  3. 向身份验证提供方上的智能体主体授予 Agent Identity User (roles/agentidentity.user) 角色：

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

    替换以下内容：

    • AUTH_PROVIDER_NAME：身份验证提供程序的名称。
    • AUTH_PROVIDER_LOCATION：身份验证提供程序的区域。
    • PRINCIPAL_IDENTIFIER：代理的主账号标识符。

    或者，对于在代理注册表中注册的代理，您可以通过创建身份验证提供方绑定来管理对身份验证提供方的访问权限。

后续步骤