Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在 GKE 上安装 Agent Substrate

标准

Agent Substrate 通过暂停空闲的智能体并在这些智能体需要再次执行操作时恢复它们，在 GKE 集群上高效运行智能体工作负载。Agent Substrate 是一款开源软件，您可以将其安装到 GKE Standard 集群中。

本文档可帮助您为 Agent Substrate 准备 Google Cloud 项目和 GKE 集群，说明如何运行安装程序，并介绍安装创建的资源。

价格

在 GKE 中，使用 Agent Substrate 无需额外付费。 GKE 价格适用于您创建的资源。

限制

Agent Substrate 存在以下安装限制：

Cloud Shell：您无法在 Cloud Shell 中安装 Agent Substrate，因为 Cloud Shell 仅提供 5 GB 的永久性磁盘存储空间，这不足以完成安装。您必须在本地机器上运行安装程序。
集群模式：您只能在 GKE Standard 集群上安装 Agent Substrate。不支持 Autopilot 集群。
现有集群和 Beta 版 API：如果您在运行 1.36 版的现有集群上启用所需的 Beta 版 API（podcertificaterequests 和 clustertrustbundles），则必须先替换现有节点，然后才能安装 Agent Substrate。在更新之前创建的节点未启用 Pod 证书投影 (MountVolume.SetUp failed: unimplemented)。在运行 1.37 版或更高版本的集群上，无需替换现有节点。
机器类型：您无法使用在混合 CPU 架构上运行的机器系列（例如 E2 机器类型）。

准备工作

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

启用 Google Kubernetes Engine API。

启用 Google Kubernetes Engine API

如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。
注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 属性。如果您主要使用可用区级集群，请改为设置 compute/zone。通过设置默认位置，您可以避免 gcloud CLI 中出现如下错误：One of [--zone, --region] must be supplied: Please specify location。如果集群的位置与您设置的默认位置不同，您可能需要在某些命令中指定位置。

在 gcloud CLI 中安装以下组件：
- kubectl
- gke-gcloud-auth-plugin
确保在本地机器上安装以下工具：
- Git 以克隆 Agent Substrate 代码库。
- Go 来运行以源代码形式分发的安装程序。
- make 以启动安装程序。
由于安装程序会代表您启用 API 和预配资源，因此请运行以下命令来设置应用默认凭据 (ADC)：
```
gcloud auth application-default login
```
如需详细了解如何使用 ADC 进行身份验证，请参阅设置应用默认凭证。

所需的角色

如需获得安装 Agent Substrate 所需的权限，请让管理员向您授予项目的以下 IAM 角色：

Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
Kubernetes Engine Admin (roles/container.admin)
Storage Admin (roles/storage.admin)
Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Monitoring Editor (roles/monitoring.editor)

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

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

集群要求

如果您让安装程序为您创建集群，它会自动配置满足 Agent Substrate 所有要求的集群。

如果您选择在现有集群上安装 Agent Substrate，则该集群必须满足以下要求：

在 GKE Standard 上运行（仅 Standard 集群支持 Agent Substrate）。
运行 GKE 1.36 版（已启用 Beta 版标志）或 1.37 版或更高版本。
为节点使用 c3-standard-4 或更大的机器类型。
已启用 PodCertificateRequest 和 ClusterTrustBundle Kubernetes API（certificates.k8s.io/v1beta1/podcertificaterequests 和 certificates.k8s.io/v1beta1/clustertrustbundles）。如需在现有集群上启用这些 API，请运行以下命令：
```
gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
```
- 版本 1.36：启用 API 后，您必须替换现有节点，例如通过升级节点池或重新创建其节点。在更新 (MountVolume.SetUp failed: unimplemented) 之前就存在的节点上，Pod 证书投影未启用。
- 版本 1.37 或更高版本：现有节点上已启用 Pod 证书投影，因此您无需在启用 API 后替换节点。

安装 Agent Substrate

如需安装 Agent Substrate，请在本地终端中运行以下命令：

curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash

交互式安装程序会提示您输入项目、集群和存储空间设置。它会尽可能建议默认值，您可以接受或自定义这些默认值：

项目 ID（必需）：指定将预配资源的 Google Cloud 项目。如果您为 gcloud CLI 配置了默认项目，安装程序会使用该项目 ID。
集群（必需）：选择是让安装程序创建具有推荐默认设置的新 GKE 集群，还是在现有集群上安装 Agent Substrate。如果您选择在现有集群上安装，请验证该集群是否满足集群要求部分中的要求。
快照存储桶（可选）：指定自定义 Cloud Storage 存储桶名称，或将其留空，让安装程序创建名为 ate-snapshots-<project>-<zone> 的默认存储桶。

当系统提示您选择容器映像来源时，您可以从以下选项中进行选择：

预构建的映像：从容器注册表中拉取已发布的映像。由于没有构建或推送任何内容，因此您的 Google Cloud 项目不需要自己的容器注册表。
从源代码构建：从上游 Agent Substrate 代码库（或自定义分支）构建映像，并将其推送到项目的 Artifact Registry 注册表。

安装程序的作用

安装程序会代表您执行以下程序：

setup-gcp：创建或验证所需的 Google Cloud 资源、启用 API、创建 GKE 集群（如果您选择不使用现有集群）和 Cloud Storage 存储桶，并配置 IAM 政策。
ate-setup：将预构建的 Agent Substrate 容器映像和控制器部署到您的 GKE 集群。

首先，安装程序会对您的 Google Cloud 项目进行以下更改：

启用 Agent Substrate 所需的 Google Cloud API。
创建具有以下设置的 GKE Standard 集群（如果未使用现有集群）：
- 适用于 GKE 的工作负载身份联合：允许 Agent Substrate 访问 Cloud Storage，而无需在节点上存储密钥。
- GKE Dataplane V2：处理将传入请求路由到代理所需的网络。
- 证书 API（PodCertificateRequest 和 ClusterTrustBundle）：启用这些 Kubernetes Beta 版 API，以便为 Agent Substrate 组件之间的 TLS 通信颁发证书。
- Managed OpenTelemetry：从集群中收集指标和跟踪记录。
创建 Agent Substrate 将快照写入到的 Cloud Storage 存储桶。
授予 Agent Substrate 对 Cloud Storage 的访问权限，以便存储快照。如果您选择从源代码进行构建，则还会授予对 Artifact Registry 中容器映像的访问权限。
创建 Cloud Monitoring 信息中心，用于绘制 Agent Substrate 的路由延迟时间、快照大小和 gRPC 流量。

接下来，安装程序会对集群进行以下更改：

向集群添加 Agent Substrate API 组和资源。这些是 Kubernetes 自定义资源，例如 ActorTemplate（用于定义代理使用的容器映像和资源）和 WorkerPool（用于定义保持就绪状态的空闲沙盒数量）。
设置用于颁发证书的证书授权机构，这些证书用于标识 Agent Substrate 的组件和您的 Actor。组件会提供这些证书，以便使用 mTLS 相互进行身份验证。
将 Agent Substrate 的组件部署到您的集群，以及一个用于跟踪 Actor 和 Worker 状态的 PostgreSQL 数据库。安装程序会等待数据库和所有控制平面 Pod 准备就绪。

Agent Substrate 将其组件部署为 ate-system 和 podcertificate-controller-system 命名空间内的普通工作负载。安装不会修改 GKE 控制平面。

部署的组件包括基于 gVisor 的运行时，Agent Substrate 默认使用该运行时将每个代理与运行它的节点隔离开来。安装程序不会配置微型虚拟机运行时。如需使用 microVM 运行时，您必须手动将其部署到已启用嵌套虚拟化的节点池中。如需了解详情，请参阅上游 Agent Substrate 代码库中的 microVM 运行时说明。

如果安装在任何时候失败（例如，由于暂时性网络错误或令牌过期），请重新运行该命令。安装程序会保留现有资源，并从上次中断的位置恢复。

如需升级现有集群上的 Agent Substrate，请运行安装程序并选择升级已安装的集群。如需了解详情，请参阅 substrate-gke 自述文件中的升级已安装的集群。

可选步骤

部署核心组件后，安装程序会提供以下可选步骤：

Filestore CSI 驱动程序：安装为 Agent Substrate 配置的 Filestore CSI 驱动程序。如果您的代理需要跨 Pod 共享文件存储空间（例如共享工作区或代码库），请选择此选项。如果您的集群已启用受管理的 GKE Filestore 插件，安装程序会在部署驱动程序之前将其停用。
节点池自动扩缩：在节点池上启用 GKE 集群自动扩缩。您可以指定节点池的最小和最大节点数。如果您希望 GKE 在需求激增期间自动添加节点，并在代理暂停时移除节点，请选择此选项。如果您希望节点数量固定且计算费用可预测，请跳过此选项。
计数器演示：部署一个示例工作负载，演示代理暂停和恢复。如果您想在安装后测试集群，请选择此选项。如需了解详情，请参阅试用计数器演示版。

验证安装

如需验证安装是否成功且核心组件是否正在运行，请运行以下命令并确保所有 Pod 的状态均为 Running：

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

节点标签和版本

安装程序会将 ate.dev/substrate-version 标签应用于集群中的每个节点。此标签用于指定集群上安装的 Agent Substrate 版本，并且 Agent Substrate 仅在具有此版本标签的节点上运行 Worker。

如需检查集群上安装的 Agent Substrate 版本，请运行以下命令：

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

请注意以下节点标签细节：

工作器池：创建 WorkerPool 时，将其配置为以该版本标记为目标。如需��看示例，请参阅 Substrate API 指南中的将池固定到已安装的基底版本。
新节点：安装程序会标记各个节点，而不是节点池。因此，安装后添加的任何新节点（即使是在安装程序创建的节点池中）在启动时都没有版本标签。您应为 GKE 节点池添加标签，以便新节点自动接收该标签。

试用计数器演示

如果您在安装程序提示时选择部署 Counter 演示应用，则可以观察 Agent Substrate 的暂停和恢复功能。该演示会运行一个小型 Web 服务器，该服务器会在内存中保存一个计数。

部署演示的 WorkerPool 和 ActorTemplate 后，安装程序会输出您需要执行的命令，以便从 ActorTemplate 创建 Actor 并向该 Actor 发送请求。上游 Agent Substrate 代码库中的 Counter 演示版 README 文件介绍了接下来要采取的步骤。

卸载 Agent Substrate

安装程序完成安装并退出后，会针对您的环境输出自定义的清理命令。

如需移除安装期间创建的资源，请选择以下选项之一：

从现有集群中移除 Agent Substrate：如果您在现有集群上安装了 Agent Substrate，并希望保留该集群及其其他工作负载，请仅通过运行安装程序打印的 ate-setup delete ate-system 命令来删除 Agent Substrate 组件。安装程序会使用安装期间配置的项目、集群和位置值预先填充此命令。
删除所有资源（包括集群）：如需删除 GKE 集群、快照存储桶、IAM 绑定和信息中心，请运行安装程序输出的 cleanup-gcp 命令。安装程序会预先填充此命令，其中包含在安装期间配置的项目、集群、位置和存储桶值。如需了解详情，请参阅 substrate-gke 自述文件的“拆解”部分。

后续步骤

如需详细了解 Agent Substrate，请参阅 Agent Substrate 简介。