在 GKE 上安装 Agent Substrate

GKE 上的 Agent Substrate 可在 GKE 集群上高效运行智能体工作负载：您的应用会暂停闲置智能体，并在它们需要再次执行操作时恢复它们。Agent Substrate on GKE 是一款开源软件，可安装到 GKE Standard 集群上。如需比较 GKE 上的 Agent Substrate 与 GKE 上的 Agent Sandbox，并为 AI 智能体工作负载选择架构，请参阅为 GKE 上的 AI 智能体工作负载规划架构。

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

价格

GKE 上的 Agent Substrate 免费提供。 GKE 价格适用于您创建的资源。

限制

Agent Substrate on GKE 存在以下安装限制：

  • Cloud Shell：您无法在 Cloud Shell 中的 GKE 上安装 Agent Substrate，因为 Cloud Shell 仅提供 5 GB 的永久性磁盘存储空间，不足以完成安装。您必须在本地机器上运行安装程序。
  • 集群模式：您只能在 GKE Standard 集群中安装 Agent Substrate。 不支持 Autopilot 集群。
  • 集群版本：集群中的控制平面和节点池都必须运行 GKE 1.37 版或更高版本。不支持 1.37 之前的版本。
  • 发布渠道：您无法在已注册到扩展发布渠道的集群中的 GKE 上安装 Agent Substrate。安装程序会在集群中启用 Kubernetes Beta 版 API，而扩展渠道不支持明确启用的 Beta 版 API。
  • 机器类型：您不能使用在混合 CPU 架构上运行的机器系列（例如 E2 机器类型）。

准备工作

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

  • 启用 Google Kubernetes Engine API。
    • 启用 Google Kubernetes Engine API
  • 如需使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。
  • 在 gcloud CLI 中安装以下组件：
    • kubectl
    • gke-gcloud-auth-plugin
  • 确保您的本地机器上安装了以下工具：
    • Git：用于克隆 Agent Substrate 代码库。
    • Go，用于运行安装程序的程序（以源代码形式分发）。
    • make 启动安装程序。
    • Docker 及其 Buildx 插件，用于在 GKE 容器映像上构建 Agent Substrate。
    • sha256sum、zstd、unzip 和 jq，用于设置 microVM 运行时（如果您打算使用它）。如果缺少其中任何一个工具，安装程序将不会提供 microVM 运行时。

  • 如需让安装程序推送其构建的映像，请配置 Docker 以向集群所在区域的 Artifact Registry 进行身份验证：

    gcloud auth configure-docker REGION-docker.pkg.dev

    将 REGION 替换为集群所在的区域，例如 us-west1。如需了解详情，请参阅为 Docker 配置向 Artifact Registry 的身份验证。

  • 由于安装程序会代表您启用 API 和预配资源，因此请运行以下命令来设置应用默认凭据 (ADC)：

    gcloud auth application-default login

    如需详细了解如何使用 ADC 进行身份验证，请参阅设置应用默认凭证。

所需的角色

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

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

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

集群要求

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

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

  • 在 GKE Standard 上运行（GKE 上的 Agent Substrate 仅在 Standard 集群上受支持）。
  • 在控制平面和节点池上运行 GKE 1.37 版或更高版本。如果控制平面运行的是较低版本，请先升级控制平面。然后，升级运行早期版本的任何节点池，以便节点可以将 Pod 证书装载到 Pod 中。
  • 未在扩展发布渠道中注册。如需了解详情，请参阅限制。
  • 使用 GKE Dataplane V2。
  • 为节点使用 c3-standard-4 或更大的机器类型。

  • 如果您计划在每个节点上运行大约 800 个以上的并发沙盒，则集群会使用在 Linux 内核中具有更高限制的节点，以便进行文件系统监控 (inotify) 和地址解析协议 (ARP) 的邻居表。如果没有这些更高的限制，沙盒可能无法启动，网络可能会停滞。节点需要以下内核设置：

    • net.ipv4.neigh.default.gc_thresh1：4096
    • net.ipv4.neigh.default.gc_thresh2：16384
    • net.ipv4.neigh.default.gc_thresh3：32768
    • fs.inotify.max_user_instances：65536
    • fs.inotify.max_user_watches：1048576

    安装程序仅会自动将这些设置应用于其创建的集群。如需将这些设置应用于现有集群中的节点池，请使用节点系统配置。如需了解详情，请参阅 Sysctl 配置选项。

在 GKE 上安装 Agent Substrate

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

  • 如需为自己的工作负载安装，请运行以下命令：

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

  • 如需安装并试用计数器演示，请运行以下命令：

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

交互式安装程序会提示您输入容器映像以及项目、集群、存储和入站流量设置。安装程序会尽可能建议推荐的默认值，您可以接受或自定义这些默认值：

  • 容器映像（必需）：当安装程序要求您选择映像时，请选择从源代码构建。安装程序会从上游 Agent Substrate 代码库构建映像，并将其推送到项目中的 Artifact Registry 代码库。默认情况下，安装程序会构建最新版本的 Agent Substrate。如需构建其他版本，请输入上游代码库中的分支、标记或完整提交 SHA。
  • 项目 ID（必需）：指定将在其中预配资源的 Google Cloud 项目。如果您为 gcloud CLI 配置了默认项目，则安装程序会使用该项目 ID。
  • 集群（必需）：选择是让安装程序使用推荐的默认设置创建新的 GKE 集群，还是在现有集群中安装 Agent Substrate on GKE。如果您选择在现有集群上安装，请验证该集群是否满足集群要求部分中的要求。
  • 快照存储桶（可选）：指定自定义 Cloud Storage 存储桶名称，或将其留空，让安装程序创建名为 ate-snapshots-<project>-<cluster>-<zone> 的默认存储桶。由于默认名称包含集群名称，因此同一项目和可用区中的集群不会共享存储桶。自定义名称最多只能包含 56 个字符，因为安装程序还会通过在名称中添加 -assets 后缀来创建资产存储桶，而存储桶名称最多只能包含 63 个字符。如果默认名称超过 56 个字符，安装程序会将其缩短并附加哈希。
  • 入站客户端（必需）：输入向 Actor 发送请求的工作负载的 SPIFFE ID，例如应用的前端或后端服务。SPIFFE ID 通过命名空间和其 Pod 运行所用的 Kubernetes 服务账号来标识工作负载。例如，在 shop 命名空间中作为 frontend 服务账号运行的 Pod 具有 SPIFFE ID spiffe://cluster.local/ns/shop/sa/frontend。由于 ID 仅取决于命名空间和服务账号，因此您可以输入尚未部署的客户端的 ID。如有多个 ID，请以英文逗号分隔。请求通过入站流量路由器到达您的 Actor，该路由器仅允许提供 Pod 证书且其 SPIFFE ID 在此列表中的客户端。列表中的任何客户端都可以访问任何 Actor。如果您添加 --demo 标志，安装程序将仅允许 Counter 演示的 Pod，而不会要求提供 ID。如需在安装后添加客户端，请参阅 substrate-gke README 中的通过入站流量路由器访问 actor。

安装程序的作用

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

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

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

  1. 启用 GKE 上的 Agent Substrate 所需的 Google Cloud API。
  2. 创建一个运行 1.37 版或更高版本且具有以下设置的 GKE Standard 集群（如果不使用现有集群）：
    • Workload Identity Federation for GKE：允许 GKE 上的 Agent Substrate 访问 Cloud Storage，而无需在节点上存储密钥。
    • GKE Dataplane V2：处理将传入请求路由到代理所需的网络。
    • Managed OpenTelemetry：从集群收集指标和跟踪记录。
  3. 创建 Agent Substrate on GKE 使用的 Cloud Storage 存储桶：一个用于存储快照，另一个用于存储 microVM 运行时所需的文件。第二个存储桶的名称是快照存储桶的名称，后跟 -assets 后缀。
  4. 为安装程序构建的容器映像创建一个名为 ate-images 的 Artifact Registry 制品库。
  5. 创建一个名为 ate-snapshot-transfer 的服务账号，供 Agent Substrate on GKE 用于传输快照。
  6. 向 GKE 节点、GKE 组件上的 Agent Substrate 以及 ate-snapshot-transfer 服务账号授予访问存储桶和容器映像所需的 IAM 权限。
  7. 创建 Cloud Monitoring 信息中心，以图表形式显示 GKE 上的 Agent Substrate 路由延迟时间、快照大小和 gRPC 流量。

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

  1. 将 GKE Kubernetes 自定义资源上的 Agent Substrate 添加到集群，例如 WorkerPool（定义有多少空闲沙盒保持就绪状态）和 SandboxConfig（定义沙盒运行时）。其他 Agent Substrate on GKE 资源（例如 ActorTemplate，用于定义智能体使用的容器映像和资源）和 Actor 不是 Kubernetes 资源。您可以通过 Agent Substrate on GKE API，使用 kubectl ate 插件（用于管理 Actor 和 Worker 的 kubectl 插件）来管理它们。如需安装该插件，请参阅安装 kubectl ate 插件。
  2. 设置证书授权机构，这些机构负责颁发用于标识 GKE 上的 Agent Substrate 组件和 Actor 的证书。 组件会提供这些证书，以便使用 mTLS 相互进行身份验证。
  3. 将 GKE 上的 Agent Substrate 组件部署到您的集群，并部署一个 PostgreSQL 数据库来跟踪 Actor 和 Worker 的状态。该数据库将其数据存储在 500 GiB 的永久性磁盘上。安装程序会等待数据库和所有控制平面 Pod 准备就绪。对于生产集群，您可以在运行安装程序之前将 PostgreSQL 数据库和系统基础架构组件隔离到专用节点池中。如需了解相关说明，请参阅隔离系统基础架构和工作器节点池。

Agent Substrate on GKE 会将其组件作为普通工作负载部署在 ate-system 和 podcertificate-controller-system 命名空间中。如果您在现有集群中安装，安装程序还会更新集群，以开启以下功能（如果这些功能处于关闭状态）：Workload Identity Federation for GKE、Managed OpenTelemetry 以及 podcertificaterequests 和 clustertrustbundles Kubernetes API 的 Beta 版。启用 Beta 版 API 会更新 GKE 控制平面，这大约需要 10 分钟。

部署的组件包括基于 gVisor 的运行时，Agent Substrate on GKE 默认使用该运行时将每个智能体与运行它的节点隔离开来。如果您在可选步骤中选择 microVM 运行时，安装程序还会将 microVM 运行时所需的文件上传到 Cloud Storage，并应用指向这些文件的集群级 SandboxConfig 资源 microvm。

使用 microVM 运行时的工作器需要能够运行虚拟机的节点。当安装程序创建集群时，它创建的节点池会启用嵌套虚拟化。如果您选择高级设置并更改机器类型，请选择支持嵌套虚拟化的机器系列，例如 C3、C4、N2 或 N4。

如果您在现有集群中安装 Agent Substrate on GKE，安装程序不会向集群添加节点池。如需使用 microVM 运行时，集群需要一个启用了嵌套虚拟化或使用 x86 裸机机器类型的节点池。您只能在创建节点池时启用嵌套虚拟化。如果集群没有此类节点池，则在您选择 microVM 运行时时，安装程序会发出警告。如果您继续操作，microVM 工作器将保持 Pending 状态。如需详细了解如何配置这些节点池（包括污点），请参阅 substrate-gke 自述文件中的沙盒运行时。

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

如需升级 GKE 上已安装的 Agent Substrate，请运行安装程序，然后选择升级已安装的集群。此选项不会更改您的集群。而是下载已安装版本和要升级到的版本的源代码，并准备升级 Runbook 使用的 ~/ate-upgrade 目录。如需执行升级，请运行安装程序输出的命令，然后按照上游 Agent Substrate 代码库中的升级运行手册（从第一步开始）进行操作。 该 Runbook 支持升级到同一次要版本的更高补丁版本，对于 1.0 及更高版本，支持升级到下一次要版本。对于低于 1.0 的版本，迁移到更高次要版本需要重新安装。如需了解详情，请参阅 substrate-gke 自述文件中的升级已安装的集群。

可选步骤

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

  • Filestore CSI 驱动程序：安装为 GKE 上的 Agent Substrate 配置的 Filestore CSI 驱动程序。如果您的代理需要永久性存储空间，并且在代理在其他节点上恢复时仍可使用，请选择此选项。每个智能体都有自己的存储空间，不与其他智能体共享。Filestore 智能体存储卷的生产环境支持处于有限正式版阶段，因此您需要申请访问权限。如需了解详情，请参阅在 GKE 上将 Filestore 智能体存储卷与 Agent Substrate 搭配使用。如果您的集群启用了托管式 GKE Filestore 插件，安装程序会在部署驱动程序之前将其停用。安装程序会在 gcp-filestore-csi-driver 命名空间中部署驱动程序，并创建一个名为 substrate-filestore-csi 的服务账号，该账号具有驱动程序所需的 IAM 权限。
  • 节点池自动扩缩：在节点池上启用 GKE 集群自动扩缩。您需要指定节点池的最小和最大节点数。如果您希望 GKE 在需求激增期间自动添加节点，并在代理暂停时移除节点，请选择此选项。如果您希望节点数量固定且计算费用可预测，请跳过此选项。如需使用自定义 ComputeClass、备用容量缓冲区和活跃智能体的缩容保护功能配置自动硬件回退，请参阅为 GKE 上的 Agent Substrate 设计基础设施。
  • 沙盒运行时：可让您选择用于隔离代理的运行时。安装程序会将 gVisor 运行时作为核心组件的一部分进行安装，因此 gVisor 运行时无需额外配置。如果您希望使用硬件虚拟化进行隔离，请选择 microVM 运行时。在为现有集群选择此选项之前，请确保该集群具有已启用嵌套虚拟化或使用 x86 裸机机器类型的节点池。如需了解详情，请参阅安装程序的作用。
  • 计数器演示：部署一个示例工作负载，演示智能体暂停和恢复。只有在启动安装程序时添加 --demo 标志，系统才会显示此步骤。如果您想在安装后测试集群，请选择此选项。如需了解详情，请参阅试用计数器演示版。

验证安装

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

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

安装 kubectl ate 插件

如需管理 Actor 和 ActorTemplate 资源，请从您安装的 Agent Substrate 版本的源代码中安装 kubectl ate 插件：

git clone --depth 1 --branch VERSION https://github.com/agent-substrate/substrate.git
cd substrate
go install ./cmd/kubectl-ate

将 VERSION 替换为您安装的 Agent Substrate 版本，例如 v1.0.0（安装程序的默认版本）。

go install 命令会将插件放置在 Go 工作区的 bin 目录中。仅当该目录位于 PATH 环境变量中时，kubectl 工具才会找到该插件。如果您的 PATH 环境变量不包含该目录，请在运行任何 kubectl ate 命令之前添加该目录：

export PATH="$PATH:$(go env GOPATH)/bin"

试用 Counter 演示

如果您在运行安装程序时添加了 --demo 标志，并选择部署 Counter 演示，则安装程序会为 Web 服务器部署 WorkerPool 和 ActorTemplate，该服务器会统计内存和文件中的请求数。当您暂停和恢复运行服务器的 Actor 时，GKE 上的 Agent Substrate 会保留这两个计数。

安装完成后，安装程序会输出演示的后续步骤：安装 kubectl ate 插件的命令，以及从 ActorTemplate 创建 Actor 的命令。在运行 kubectl ate 命令之前，请确保该插件位于 PATH 环境变量中，如安装 kubectl ate 插件中所述。

安装程序不会输出向 Actor 发送请求的命令。入站流量路由器仅允许提供其 SPIFFE ID 位于其许可清单中的 Pod 证书的客户端，因此它会拒绝您直接从本地机器发送的请求。如需详细了解该演示，请参阅 Agent Substrate 1.0.0 版的计数器演示自述文件，安装程序会默认部署该版本。在安装程序设置的集群中，出于同样的原因，通过端口转发发送请求的 README 步骤不起作用。

在 GKE 上卸载 Agent Substrate

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

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

  • 从现有集群中移除 Agent Substrate on GKE：如果您在现有集群上安装了 Agent Substrate on GKE，并且想要保留该集群及其其他工作负载，请运行安装程序输出的 ate-setup delete ate-system 命令，仅删除 Agent Substrate on GKE 组件。安装程序会使用安装期间配置的项目、集群和位置值预先填充此命令。

  • 删除所有资源（包括集群）：如需删除 GKE 集群、快照和资产存储桶、ate-snapshot-transfer 服务账号、IAM 绑定、信息中心和 ate-images Artifact Registry 代码库，请运行安装程序输出的 cleanup-gcp 命令。安装程序会使用安装期间配置的项目、集群、位置和存储桶值预先填充此命令。由于该命令使用相对路径运行 tools/cleanup-gcp 脚本，因此请从安装程序克隆 substrate-gke 代码库的目录中运行该命令。默认情况下，安装程序会将代码库克隆到 ~/.substrate-gke 目录中。

    如果项目中的其他集群在 GKE 上运行 Agent Substrate，请在命令中添加 --cluster-scoped 标志。此标志会保留这些集群共享的信息中心、ate-snapshot-transfer 服务账号和项目级 IAM 绑定。--cluster-scoped 标志不会保留 ate-images 代码库。如果同一区域中的其他集群使用 ate-images 代码库，请在命令末尾添加 --keep-repository 标志。如需了解详情，请参阅 substrate-gke 自述文件的“拆解”部分。

cleanup-gcp 命令不会删除以下资源：

  • PostgreSQL 数据库的永久性磁盘：GKE 在删除集群时会保留永久性磁盘，因此您需要继续为 500 GiB 磁盘付费。如需删除磁盘，请运行安装程序输出的 ate-setup delete ate-system 命令。然后，等到 kubectl get pv 命令不再列出 ate-system/data-postgres-0 声明的卷，再运行 cleanup-gcp。如果您已删除集群，请运行以下命令找到磁盘，然后运行 gcloud compute disks delete 命令删除磁盘：

    gcloud compute disks list --filter="description~data-postgres-0"

  • substrate-filestore-csi 服务账号：项目中运行 Filestore CSI 驱动程序的所有集群都共享此服务账号。如果您安装了驱动程序，并且项目中没有其他集群运行该驱动程序，请运行以下命令来删除服务账号：

    gcloud iam service-accounts delete substrate-filestore-csi@PROJECT_ID.

    将 PROJECT_ID 替换为您的项目 ID。

后续步骤