在 GKE 上安装 Agent Substrate

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

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

价格

GKE 上的智能体基质免费提供。 GKE 定价 适用于您创建的资源。

限制

GKE 上的智能体基质具有以下安装限制：

  • Cloud Shell：您无法在 Cloud Shell 中安装 GKE 上的智能体基质，因为 Cloud Shell 提供 5 GB 的永久性磁盘存储空间，这不足以进行 安装。您必须在本地机器上运行安装程序。
  • 集群模式：您只能在 GKE Standard 集群中安装 GKE 上的智能体基质。 不支持 Autopilot 集群。
  • 现有集群和 Beta 版 API：如果您在运行 1.36 版的现有集群上启用所需的 Beta 版 API （podcertificaterequests 和 clustertrustbundles），则必须先替换现有节点，然后才能安装 GKE 上的智能体基质。在更新之前创建的节点未启用 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 中安装以下组件：
    • kubectl
    • gke-gcloud-auth-plugin
  • 确保在本地机器上安装了以下工具：
    • Git，用于克隆 智能体基质代码库。
    • Go，用于运行安装程序的程序，这些程序 以源代码形式分发。
    • make，用于启动安装程序。

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

    gcloud auth application-default login

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

所需的角色

如需获得在 GKE 上安装智能体基质所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

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

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

集群要求

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

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

  • 在 GKE Standard 上运行（GKE 上的智能体基质仅在 Standard 集群上受支持）。
  • 运行 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 后，您必须 替换现有节点，例如升级节点池或重新创建其节点。在更新之前存在的节点上未启用 Pod 证书投影（MountVolume.SetUp failed: unimplemented）。
    • 1.37 版或更高版本：Pod 证书投影已在现有节点上启用 ，因此您无需在启用 API 后替换节点 。

安装 GKE 上的智能体基质

如需安装 GKE 上的智能体基质，请在本地终端中运行以下命令：

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

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

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

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

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

安装程序的作用

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

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

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

  1. 启用 GKE 上的智能体基质所需的 Google Cloud API。
  2. 创建具有以下设置的 GKE Standard 集群（如果未使用现有集群）：
    • Workload Identity Federation for GKE：允许 GKE 上的智能体基质访问 Cloud Storage，而无需在节点上存储密钥。
    • GKE Dataplane V2：处理将传入 请求路由到智能体所需的网络。
    • 证书 API（PodCertificateRequest 和 ClusterTrustBundle）：启用这些 Kubernetes Beta 版 API，以便为 GKE 上的智能体基质组件之间的 TLS 通信 颁发证书。
    • 代管式 OpenTelemetry：从您的 集群收集指标和跟踪记录。
  3. 创建 GKE 上的智能体基质将快照写入的 Cloud Storage 存储桶。
  4. 授予 GKE 上的智能体基质对 Cloud Storage 的访问权限，以存储快照。如果您选择从源代码构建，还会授予对 Artifact Registry 的访问权限，以访问容器映像。
  5. 创建 Cloud Monitoring 信息中心，用于绘制 GKE 上的智能体基质路由延迟时间、快照大小和 gRPC 流量。

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

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

GKE 上的智能体基质将其组件部署为 ate-system 和 podcertificate-controller-system 命名空间中的普通工作负载。安装不会修改 GKE 控制平面。

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

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

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

可选步骤

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

  • Filestore CSI 驱动程序：安装为 GKE 上的智能体基质配置的 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 标签应用于集群中的每个节点。此标签指定在集群上安装的 GKE 上的智能体基质的版本，并且 GKE 上的智能体基质仅在具有此版本标签的节点上运行 Worker。

如需检查在集群上安装的 GKE 上的智能体基质的版本，请运行以下命令：

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

请注意以下节点标签详细信息：

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

试用计数器演示

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

部署演示的 WorkerPool 和 ActorTemplate 后，安装程序 会输出您需要使用的命令，以便从 ActorTemplate 创建 Actor 并 向该 Actor 发送请求。上游智能体基质代码库中的 计数器演示自述文件 介绍了后续 步骤。

卸载 GKE 上的智能体基质

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

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

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

  • 删除所有资源（包括集群）：如需删除 GKE 集群、快照存储桶、IAM 绑定 和信息中心，请运行安装程序输出的 cleanup-gcp 命令。 安装程序会使用在安装期间配置的项目、集群、位置和存储桶值预先填充此命令。 如需了解详情，请参阅 substrate-gke 自述文件的“Tearing down”部分。

后续步骤