与其他类型的工作负载相比,代理工作负载通常需要不同的防御措施、访问权限控制和身份验证工作流程。您可以使用代理身份为每个代理提供经过证明的短暂的每个 Pod 身份。此身份可帮助您识别代理工作负载,并跟踪和管理这些工作负载在 Google Cloud中的操作。本文档介绍了代理身份在 Google Kubernetes Engine (GKE) 中的运作方式,包括如何与其他Google Cloud 产品集成、代理可以使用的身份验证类型,以及如何使用这些身份来管理工作负载。
本文档面向平台管理员和安全工程师,旨在帮助他们在将代理与 Google Cloud 产品和服务集成时,提高在 GKE 集群上运行的代理的安全性。
您应该已经熟悉以下主题:
什么是智能体身份?
Google Cloud 为工作负载提供各种身份类型,每种身份类型都适用于特定的一组使用情形和工作负载类型。智能体身份是一种专为 AI 智能体工作负载设计的身份类型。使用智能体身份的智能体可获得基于 SPIFFE 标准的唯一身份。此身份与智能体的生命周期相关联,可将工作负载标识为智能体,并可被各种 Gemini Enterprise Agent Platform 服务(如 Agent Registry 和 Agent Gateway)识别。您可以跟踪和管理具有代理身份的工作负载,无论该工作负载在何处运行,都可以跨该工作负载访问的所有服务进行跟踪和管理。使用代理身份的工作负载可以使用自己的身份或代表最终用户向 MCP 服务器、 Google Cloud内外的资源、其他代理和端点进行身份验证。如需详细了解智能体身份,请参阅智能体身份概览。
您可以使用代理身份来提高在 GKE 集群中部署的 AI 代理的安全性和治理水平,并为代理启用特定工作流,例如:
- 将 GKE 上的智能体与 Agent Registry 和 Agent Gateway 等产品集成。
- 在 Identity and Access Management (IAM) 政策中管理代理工作负载在项目、文件夹或组织中的角色。
- 降低受入侵的代理对节点和集群中其他 Pod 的影响。
- 使用 Agent Identity 身份验证管理器 设置各种工作流,例如代理代表最终用户执行操作。
与 Workload Identity Federation for GKE 的比较
代理身份和 Workload Identity Federation for GKE 均提供为工作负载赋予身份的方法。Agent Identity 是根据适用于 AI 智能体的威胁模型和特定要求设计的,因此在功能上存在各种差异。下表简要比较了这些区别:
| Agent Identity | Workload Identity Federation for GKE |
|---|---|
| 代理身份访问令牌可以与每个 Pod 的 X.509 证书进行加密绑定。绑定访问令牌需要 mTLS 连接,并且在原始 Pod 之外使用时无法正常运行。 | 联合访问令牌在加密方面与 Pod 身份无关,可通过非 mTLS 连接使用,并且可在原始 Pod 之外使用。 |
| 与 Agent Identity 身份验证管理器集成,以支持 OAuth 工作流并使用第三方凭证,而无需手动管理凭证。 | 在对外部工具和服务进行身份验证时,需要手动实现 OAuth 工作流并管理第三方凭据。 |
| 非常适合 AI 智能体等自主工作负载。 | 非常适合 Web 服务器、API 和批量作业等确定性微服务。 |
| 需要 GKE 1.37.0-gke.3503000 或更高版本。 | 适用于所有 GKE 版本。 |
绑定代理身份访问令牌始终使用 https://www.googleapis.com/auth/cloud-platform 访问权限范围。不支持自定义范围。 |
联合访问令牌支持自定义访问权限范围。 |
| 应用可以获取代理身份 ID 令牌,以便直接向其他工作负载或下游服务进行身份验证。 | 除非 Kubernetes 服务账号配置为模拟 IAM 服务账号,否则应用无法获取 ID 令牌。 |
与 Agent Platform 集成
Gemini Enterprise Agent Platform 包含多款产品和服务,旨在帮助您大规模构建、治理和运行智能体。如果您在 GKE 上运行代理工作负载,则可以通过以下方式使用 Agent Platform 产品:为工作负载分配代理身份,并在 Agent Registry 中将工作负载注册为代理。为了将代理平台服务与 GKE 代理集成并使用,应用运维人员需要向代理工作负载的 Kubernetes 规范添加注解和标签。除了验证是否已启用 Workload Identity Federation for GKE 之外,您无需更改集群或节点池配置。然后,您可以像管理在 Agent Runtime 或 Cloud Run 上运行的代理一样管理和控制 GKE 代理。
在代理注册表中注册还有助于防止在组织之间迁移项目时可能出现的中断。在项目迁移期间,Agent Registry 会检查是否有任何代理使用基于组织级信任域的 Agent Identity,该身份会在迁移后发生变化。如果正在使用组织级代理身份,则项目迁移会被阻止。此检查仅针对您在代理注册表中注册的部署进行。其他工作负载控制器或静态 Pod 不会进行此检查。
在 GKE 中的运作方式
在 GKE 中,代理身份使用 GKE 元数据服务器和身份池等概念,与 Workload Identity Federation for GKE 类似。如需使用代理身份,您还必须在集群中启用 Workload Identity Federation for GKE。 Google Cloud 会自动在项目或组织级层创建代理身份池。代理身份池是一个 SPIFFE 信任域,是代理身份和凭据的信任根。应用开发者可以通过向其 Pod 规范添加注释和标签,为其代理请求代理身份。 当工作负载部署到集群时,GKE 会为该工作负载分配以下凭据:
用于标识工作负载的 SPIFFE 身份。受管工作负载(例如 Deployment)中的所有 Pod 共享该工作负载的 SPIFFE ID。SPIFFE ID 用于在 Google Cloud 服务中标识代理。您可以使用 SPIFFE ID 跟踪 Pod 执行的任何操作,无论是作为代理执行还是代表最终用户执行。SPIFFE ID 的语法如下:
spiffe://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/NAMESPACE/sa/SERVICEACCOUNT_NAME此 ID 字符串具有以下属性:
TRUST_DOMAIN:SPIFFE 信任域,具有以下值之一,具体取决于包含集群的项目是否位于组织中:- 组织中的项目:
agents.global.org-ORGANIZATION_ID.system.id.goog,其中ORGANIZATION_ID是组织的 ID。 - 不在组织中的项目:
agents.global.proj-PROJECT_NUMBER.system.id.goog,其中PROJECT_NUMBER是集群项目的项目编号。
- 组织中的项目:
PROJECT_NUMBER:集群项目的项目编号。CONTROL_PLANE_LOCATION:集群控制平面所在的区域或可用区。CLUSTER_NAME:Pod 所在集群的名称。NAMESPACE:Pod 所在的 Kubernetes 命名空间的名称。SERVICEACCOUNT_NAME:分配给 Pod 的 Kubernetes ServiceAccount 的名称。
代理身份凭据软件包 (
x509.credential-bundle.private-key.pem),以卷的形式装载在每个 Pod 中,可用于对 Google Cloud API 进行 mTLS 身份验证。此文件包含以下凭据:- 一个 X.509 证书链,其中包含代理工作负载的 SPIFFE ID 作为主体备用名称 (SAN) 参数,并在 24 小时后过期。证书链用于获取绑定访问令牌和身份令牌,以便向其他服务进行身份验证。
kubelet进程自动为每个 Pod 创建的私钥。该密钥以加密方式将 Pod 的 X.509 证书绑定到 Pod。此密钥可证明发出请求的 Pod 拥有用于建立 TLS 连接的 X.509 证书。
一个根 CA 信任软件包 (
TRUST_DOMAIN.spiffe-trust-bundle.pem),作为卷装载在每个 Pod 中,可用于在使用同一信任域的代理之间配置 mTLS 身份验证。在 mTLS 握手期间,代理会使用根 CA 信任软件包来验证对等代理提供的证书链。
工作负载级配置
如需为工作负载分配代理身份和每个 Pod 的凭据,GKE 会在 Pod 规范中查找以下注释:
iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*":GKE 使用此注解为 Pod 分配相应信任域中的 SPIFFE ID。iam.gke.io/inject-podcertificates: "true":GKE 使用此注解将代理身份凭据软件包和集群信任软件包添加到工作负载中的每个 Pod。如果省略此注解,则无法获取绑定到特定 Pod 的访问令牌。注入的凭据用于从您的 Pod 到任何Google Cloud API 或对等代理的 mTLS 身份验证。
此外,代理注册表还使用以下标签和注解来自动注册您的 GKE 代理:
registry.gke.io/functional-type: "AGENT"标签:将工作负载标识为 AI 智能体,并将该智能体添加到 Agent Registry。此标签仅受 Deployment 支持,并且必须在 Deployment 清单的metadata.labels字段中指定。iam.gke.io/spiffe-identity-type: "agent-identity"注解:表示代理使用代理身份。此注解在 Pod 规范中指定。如果为 Deployment 指定了registry.gke.io/functional-type: "AGENT"标签,则必须在 Pod 规范中添加此注解。
如需将 GKE 代理与 Agent Platform 集成,除了使用代理身份之外,还需向代理注册表注册工作负载。考虑在部署流水线中强制执行代理工作负载注册或自动执行注册。
智能体的访问令牌
在 GKE 中,使用代理身份的每个 Pod 都会获得一个唯一的凭据包,其中包含 X.509 证书和 Pod 的私钥,该私钥不会离开 Pod。如需访问任何 Google Cloud API 或外部服务,GKE 集群中的代理 Pod 会从在每个节点上运行的 GKE 元数据服务器请求代理身份访问令牌。Pod 使用代理身份访问令牌来验证代理身份。
访问令牌可以绑定,也可以不绑定,如下所示:
- 绑定访问令牌:以加密方式绑定到 Pod 的 X.509 证书,只能通过使用该 X.509 证书进行身份验证的 mTLS 连接使用。任何在载荷中包含 X.509 证书的访问令牌请求都会生成绑定令牌。
- 无绑定访问令牌:未以加密方式绑定到特定 Pod,可通过非 mTLS 连接使用。未绑定的访问令牌更容易受到令牌重放攻击,因为泄露的令牌可供其他 Pod 使用。
代理使用绑定或未绑定的访问令牌向Google Cloud API 进行身份验证。身份管理员可以在 IAM 政策中指定代理身份访问令牌的主账号标识符,从而控制代理的访问权限,如控制代理对 Google Cloud 资源的访问权限中所述。
如果 Pod 具有 iam.gke.io/inject-podcertificates: "true" 注解,则 Cloud 客户端库和 Google 身份验证库会使用应用默认凭据 (ADC) 自动为 Pod 获取绑定的代理身份访问令牌。此自动流程可能不会在所有库或编程语言中发生。如需改为请求无绑定访问令牌,开发者可使用以下方法之一:
在 Pod 规范中指定
iam.gke.io/inject-podcertificates: "true"注解,并将GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN环境变量设置为false值。GKE 会将 X.509 凭据软件包添加到 Pod,但环境变量会导致 ADC 获取未绑定的访问令牌。此方法可让 Pod 继续使用证书与其他工作负载建立 mTLS 连接,同时使用无绑定访问令牌来访问 Google Cloud API。
请勿在 Pod 规范中指定
iam.gke.io/inject-podcertificates: "true"注解。GKE 不会将 X.509 凭据软件包添加到 Pod,因此 ADC 会为 Pod 获取无绑定访问令牌。向 GKE 元数据服务器的令牌端点发送直接 HTTP
GET请求,该请求会返回未绑定的访问令牌。
代理的身份验证工作流
与非代理工作负载不同,代理可能需要代表最终用户或以代理自身的身份向服务进行身份验证,具体取决于代理尝试执行的任务。代理身份支持使用各种凭据和身份验证模型对以下类型的资源进行身份验证:
- Google Cloud API
- 外部工具和服务
- 代理到代理身份验证
向 Google Cloud API 进行身份验证
代理可以使用自己的身份向 Google Cloud API(例如 BigQuery 或 Agent Platform)进行身份验证。为了进行身份验证,Pod 会从节点上的 GKE 元数据服务器获取代理身份访问令牌。此访问令牌可以选择性地绑定到 Pod 的 X.509 证书,这意味着该访问令牌只能通过使用 X.509 证书进行身份验证的 mTLS 连接来使用。
如果您的应用使用 google-auth Python 身份验证库的 2.61.0 版或更高版本,则应用默认凭据 (ADC) 会自动为具有 Agent Identity 凭证软件包的 Pod 请求绑定访问令牌。如果您使用适用于 Python 的 Cloud 客户端库,请确保您使用的版本包含 google-auth 库的 2.61.0 版或更高版本。对于其他编程语言或低于 2.61.0 版本的 google-auth Python 库,请改为请求无绑定访问令牌。
如果您获得的是绑定访问令牌,则必须使用 Pod 的 X.509 证书与目标 API 的 mTLS 端点建立 mTLS 连接。如果您获得的是非绑定访问令牌,则可以在向相应 API 的非 mTLS 端点发送的请求中使用该令牌。
如需配置应用代码以使用这些方法获取绑定或非绑定访问令牌,请参阅在 GKE 中使用代理身份进行身份验证。
如果您是平台管理员或安全管理员,则无需为向Google Cloud API 进行身份验证的代理配置额外的身份验证。您可以使用 IAM 政策来控制对资源的访问权限,如控制代理对 Google Cloud 资源的访问权限中所述。
代理对外部服务的身份验证
智能体通常需要使用特定的凭证(例如 API 密钥或 OAuth 令牌)来访问外部工具和服务。代理可能需要以自己的身份或代表最终用户进行身份验证。您可以使用 Agent Identity 身份验证管理器(预览版)为代理提供特定凭据。身份验证管理器可集中处理您在 Google Cloud中运行的代理的凭据获取和身份验证工作流配置。
在身份验证管理器中,您可以配置身份验证提供方来处理特定的身份验证工作流。当 GKE 中的代理需要使用特定凭据进行身份验证时,Pod 会使用其代理身份访问令牌向身份验证管理器进行身份验证。然后,身份验证提供方会处理任何额外的身份验证步骤,并将所请求的凭据返回给 Pod。身份验证管理器会将外部凭据交换为短期有效的访问令牌,这样一来,长期有效的刷新令牌和 API 密钥 就不会存储在代理容器中。
您可以在以下使用情形中使用身份验证管理器,每种情形都需要在身份验证管理器和应用代码中进行特定设置和配置:
- 代表最终用户访问外部服务。
- 以自己的身份访问外部服务。
- 使用 API 密钥访问 API。
您可以监控并撤消身份验证管理器创建的凭据。您还可以跟踪特定代理使用的凭据,因为代理会使用其代理身份访问令牌向身份验证管理器进行身份验证。以下部分介绍了身份验证管理器的使用场景以及相应的身份验证模型。根据您使用的身份验证模型,您和您的应用开发者需要对代理代码和客户端应用进行特定更改。
代表最终用户访问外部服务
最终用户可能会要求代理代表用户执行某些操作,例如在 Slack 渠道中撰写消息或在 GitHub 代码库中打开拉取请求。在这些场景中,用户通过明确同意代理代表自己行事,将自己的权限委托给代理。如需设置用户同意和凭据检索,您可以使用三方模式 OAuth,其中涉及以下步骤:
- 身份验证提供方会重定向用户,以便用户向外部服务进行身份验证。
- 用户登录并批准代理所需的访问权限。
- 外部服务向身份验证提供方返回凭据。
如需为在 GKE 上运行的代理配置三方 OAuth,平台管理员和应用开发者需按以下步骤操作:
- 平台管理员设置身份验证提供方:
- 在身份验证管理器中创建三方模式 OAuth 身份验证提供方。
- 配置身份验证提供方以重定向到第三方授权服务器。
- 配置第三方服务,以将用户访问令牌发送给身份验证提供方。
- 授权代理访问身份验证提供方。
- 应用开发者修改应用:
- 修改代理代码以使用身份验证提供程序进行身份验证。
- 修改客户端应用代码,以处理用户登录、重定向和对话恢复。
如需详细了解如何配置身份验证提供程序以及如何修改代理和客户端应用,请参阅使用身份验证管理器通过三方模式 OAuth 进行身份验证。
以代理身份访问外部服务
代理可能需要使用自己的身份访问 ServiceNow 或 Salesforce 等外部服务。例如,产品目录管理系统代理可能会监控销售数据并订购库存,以避免在销售旺季出现库存问题。在这些场景中,您可以使用双向 OAuth,该方法涉及以下步骤:
- 身份验证管理器向外部服务请求访问令牌。
- 外部服务验证请求,并将访问令牌返回给身份验证管理器。
如需为在 GKE 上运行的代理配置双向 OAuth,请执行以下操作:
- 平台管理员设置身份验证提供方:
- 从外部服务获取 OAuth 客户端 ID、客户端密钥和令牌端点。
- 在身份验证管理器中创建一个具有外部服务的 OAuth 信息的两方模式 OAuth 身份验证提供方。
- 授权代理访问身份验证提供方。
- 应用开发者修改代理代码,以使用身份验证提供程序进行身份验证。
如需详细了解如何配置身份验证提供程序和修改代理代码,请参阅使用双向 OAuth 和身份验证管理器进行身份验证。
使用 API 密钥访问 API
您可以将 API 密钥存储在身份验证管理器中,供代理用于向外部 API 进行身份验证。虽然您也可以将 API 密钥存储在其他保险库(例如 Secret Manager)中,但使用身份验证管理器方法可让您在一个中心位置跟踪和管理代理对 API 密钥的访问权限。如需在身份验证管理器中存储和使用 API 密钥,请执行以下操作:
- 平台管理员设置身份验证提供方:
- 在身份验证管理器中创建 API 密钥身份验证提供方。
- 在身份验证提供程序中生成并存储 API 密钥。
- 授权代理访问身份验证提供方。
- 修改代理代码以使用身份验证提供程序进行身份验证。
如需了解详情,请参阅使用身份验证管理器通过 API 密钥进行身份验证。
代理到代理身份验证
本部分介绍了一种高级身份验证工作流。您应该已经熟悉以下主题:
- JSON Web 令牌 (JWT):代理身份 ID 令牌是已签名的 JWT。
- JSON 对象签名和加密 (JOSE) 标头:ID 令牌具有一个 JOSE 标头,用于描述 ID 令牌的算法和签名密钥。
- JSON Web 密钥 (JWK):JWK 用于对 ID 令牌进行签名。代理身份池的公共 JWK 以 JSON Web 密钥集 (JWKS) 的形式发布。您可以使用这些公钥来验证来自其他代理的传入 ID 令牌。
在多智能体架构中,智能体通常通过直接调用对等智能体或下游服务来协作。您可以使用代理身份身份令牌(一种可从 GKE 元数据服务器获取的已签名 JWT)直接在代理工作负载之间建立通信。如需对代理服务之间的连接进行身份验证,应用开发者应执行以下操作:
- 从 GKE 元数据服务器获取调用代理的代理身份 ID 令牌。此 ID 令牌必须将
aud声明设置为接收代理的端点。 - 将 ID 令牌添加到 HTTP 请求的
Authorization: Bearer请求标头中。 - 在接收代理中,使用代理身份池的公共 JWK 以及 ID 令牌中的各种标头和正文参数来验证传入的 ID 令牌。
如需详细了解如何在应用代码中请求、使用和验证 ID 令牌,请参阅向其他代理进行身份验证。
代理到代理的身份验证不需要平台管理员进行额外的 Google Cloud配置,因为此工作流会绕过 IAM 授权检查。相反,代理会直接相互通信,并根据代理身份授权操作。
控制代理对 Google Cloud 资源的访问权限
安全管理员可以使用引用代理主账号标识符的 IAM 政策来控制代理可以访问哪些资源。如需控制对在 GKE 上运行且具有代理身份的代理的资源访问权限,请在 IAM 政策中添加以下主账号标识符之一:
特定信任域中的所有代理:
principalSet://TRUST_DOMAIN/*在此标识符中,
TRUST_DOMAIN是资源层次结构的信任网域,具体取决于代理是否位于组织中的项目中:- 组织中的项目:
agents.global.org-ORGANIZATION_ID.system.id.goog,其中ORGANIZATION_ID是组织的 ID。 - 不属于组织的项目:
agents.global.proj-PROJECT_NUMBER.system.id.goog,其中PROJECT_NUMBER是集群项目的项目编号。
- 组织中的项目:
信任域中的单个代理:
principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/NAMESPACE_NAME/sa/SERVICEACCOUNT_NAME在此标识符中,以下参数用于标识特定代理:
PROJECT_NUMBER:集群项目的项目编号。CONTROL_PLANE_LOCATION:集群控制平面所在的区域或可用区。CLUSTER_NAME:代理所在的集群的名称。NAMESPACE_NAME:代理所在的 Kubernetes 命名空间的名称。SERVICEACCOUNT_NAME:代理工作负载使用的 Kubernetes ServiceAccount 的名称。
如需详细了解如何查找 GKE 代理的主账号标识符并管理访问权限,请参阅管理代理对 Google Cloud API 的访问权限。
代理身份支持所有 IAM 政策类型,例如允许政策、拒绝政策和 Principal Access Boundary (PAB) 政策。如需管理使用代理身份的 GKE 集群中代理的访问权限,请在相应的政策类型中添加代理的主账号标识符。如需详细了解如何配置每种类型的 IAM 政策,请参阅以下主题:
查看和管理 Google Cloud中的代理
如果应用开发者在代理注册表中注册了其代理,那么您可以在 Google Cloud中查看 GKE 代理以及您运行的其他代理。代理注册表会显示代理的 SPIFFE 身份、代理的运行位置以及有关代理的任何其他信息。所有通过使用 Agent Identity 进行身份验证的 API 请求都会生成 Agent Registry 审核日志。根据代理使用的身份验证工作流,Cloud Audit Logs 提供以下信息:
- 使用代理自身的身份进行身份验证:生成的审核日志包含代理的主账号标识符,您可以使用该标识符查找代理的集群、命名空间和服务账号。
- 代表最终用户执行的委托操作:生成的审核日志包含以下信息:授权操作的最终用户,以及执行调用的代理的 SPIFFE ID。审核日志中的这种身份关联有助于您验证最终用户是否授权了特定操作。
除了 Cloud Audit Logs 之外,应用开发者还可以配置其代理工作负载以发出跟踪记录、日志和指标,这些内容会在 Google Cloud Observability 中显示。 如需详细了解如何配置工作负载,请参阅以下文档:
提高 GKE 代理的安全性
安全管理员可以通过引用代理身份来单独管理代理特定的安全措施,而无需考虑其他类型工作负载的限制。在运行代理时,请考虑采取以下防御措施:
- 为了限制遭入侵的代理的影响,请为代理身份配置Principal Access Boundary Policy(PAB 政策)。
- 如需提高身份验证管理器身份验证提供程序安全性,请为代理身份配置组织政策。
- 如需集中管理代理并跟踪各个资源中的代理操作,请使用准入控制器(例如 ValidatingAdmissionPolicies 和 MutatingAdmissionPolicies)通过注释和标签强制执行代理注册表注册。
- 如需管理直接代理到代理流量的安全性,请使用以下控制措施:
- 如需控制同一集群中 Pod 之间的流量,请使用 Kubernetes NetworkPolicies。
- 为降低在遭到入侵时发生数据渗漏的风险,请使用 VPC Service Controls。
- 如需控制 VPC 网络之间以及在不同环境中运行的代理之间的网络流量,请使用 VPC 网络防火墙政策和 Cloud Next Generation Firewall (Cloud NGFW)。
- 如需对在 Agent Registry 中注册的代理之间的流量强制执行 IAM 政策,请使用Agent Gateway。
限制
- 您只能在代理注册表中自动注册部署。 其他工作负载控制器和静态 Pod 不支持自动注册。
- 绑定代理身份访问令牌仅使用
https://www.googleapis.com/auth/cloud-platformOAuth 范围。您无法为绑定访问令牌指定其他范围。 - 只有使用 2.61.0 版或更高版本的
google-auth库的 Python 应用才支持自动检索绑定访问令牌或 ID 令牌。如果您使用 Python 版 Cloud 客户端库,则必须使用包含google-auth库 2.61.0 版或更高版本的版本。 - 某些 Cloud 客户端库可能不会自动将您的请求路由到 mTLS 端点。
- 对于代理到代理的身份验证,您只能使用绑定 ID 令牌在同一代理身份信任网域中的代理之间进行身份验证。