在 GKE 上安裝 Agent Substrate

Agent Substrate 會暫停閒置的代理，並在代理需要再次執行動作時還原，藉此在 GKE 叢集上有效率地執行代理工作負載。Agent Substrate 是開放原始碼軟體，可安裝在 GKE Standard 叢集上。

本文說明如何準備 Google Cloud 專案和 GKE 叢集以使用 Agent Substrate，並說明如何執行安裝程式，以及安裝程序建立的資源。

定價

在 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 中安裝下列元件：
    • kubectl
    • gke-gcloud-auth-plugin
  • 請確認本機電腦已安裝下列工具：
    • Git，複製 Agent Substrate 存放區。
    • 前往執行安裝程式的程式，這些程式會以原始碼形式發布。
    • make 啟動安裝程式。

  • 由於安裝程式會代表您啟用 API 並佈建資源，請執行下列指令，設定應用程式預設憑證 (ADC)：

    gcloud auth application-default login

    如要進一步瞭解如何使用 ADC 進行驗證，請參閱「設定應用程式預設憑證」。

必要的角色

如要取得安裝 Agent Substrate 所需的權限，請要求管理員授予您專案的下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

叢集需求

如果讓安裝程式為您建立叢集，系統會自動設定符合 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。如果選擇在現有叢集上安裝，請確認叢集符合「叢集需求條件」一節中的規定。
  • 快照 bucket (選用)：指定自訂 Cloud Storage bucket 名稱，或留空讓安裝程式建立名為 ate-snapshots-<project>-<zone> 的預設 bucket。

系統提示選取容器映像檔來源時，您可以選擇下列選項：

  • 預先建構的映像檔：從容器登錄檔提取已發布的映像檔。 由於沒有建構或推送任何內容， Google Cloud 專案不需要專屬的 Container Registry。
  • 從來源建構：從上游的 Agent Substrate 存放區 (或自訂分支) 建構映像檔，並推送至專案的 Artifact Registry 登錄檔。

安裝程式的用途

安裝程式會代您執行下列程式：

  • setup-gcp：建立或驗證必要 Google Cloud 資源、啟用 API、建立 GKE 叢集 (如果您選擇不使用現有叢集) 和 Cloud Storage bucket，以及設定 IAM 政策。
  • ate-setup：將預先建構的 Agent Substrate 容器映像檔和控制器部署至 GKE 叢集。

首先，安裝程式會對 Google Cloud 專案進行下列變更：

  1. 啟用 Agent Substrate Google Cloud 所需的 API。
  2. 建立 GKE Standard 叢集 (如果未使用現有叢集)，並採用下列設定：
    • Workload Identity Federation for GKE：可讓 Agent Substrate 存取 Cloud Storage，不必將金鑰儲存在節點上。
    • GKE Dataplane V2：處理將傳入要求路由至代理程式所需的網路。
    • 憑證 API (PodCertificateRequest 和 ClusterTrustBundle)：啟用這些 Kubernetes Beta 版 API，為 Agent Substrate 元件之間的 TLS 通訊核發憑證。
    • 代管 OpenTelemetry：從叢集收集指標和追蹤記錄。
  3. 建立 Cloud Storage bucket，供 Agent Substrate 寫入快照。
  4. 授予 Agent Substrate Cloud Storage 的存取權，以儲存快照。如果您選擇從來源建構，系統也會授予容器映像檔的 Artifact Registry 存取權。
  5. 建立 Cloud Monitoring 資訊主頁，繪製 Agent Substrate 的路由延遲時間、快照大小和 gRPC 流量圖表。

接著，安裝程式會對叢集進行下列變更：

  1. 將 Agent Substrate API 群組和資源新增至叢集。這些是 Kubernetes 自訂資源，例如 ActorTemplate (定義代理程式使用的容器映像檔和資源) 和 WorkerPool (定義要保持待命的閒置沙箱數量)。
  2. 設定核發憑證的憑證授權單位，以識別 Agent Substrate 的元件和您的 Actor。元件會出示這些憑證，透過 mTLS 相互驗證。
  3. 將 Agent Substrate 的元件部署至叢集，以及追蹤 Actor 和 Worker 狀態的 PostgreSQL 資料庫。安裝程式會等待資料庫和所有控制層 Pod 準備就緒。

Agent Substrate 會將元件部署為 ate-system 和 podcertificate-controller-system 命名空間內的普通工作負載。安裝作業不會修改 GKE 控制層。

部署的元件包括以 gVisor 為基礎的執行階段，Agent Substrate 預設會使用這個執行階段，將每個代理與執行的節點隔離。安裝程式不會設定 microVM 執行階段。如要使用 microVM 執行階段，您必須手動將其部署到已啟用巢狀虛擬化的節點集區。詳情請參閱上游 Agent Substrate 存放區中的 microVM 執行階段指令。

如果安裝作業在任何時間點失敗 (例如因為網路暫時發生錯誤或權杖過期)，請重新執行指令。安裝程式會保留現有資源，並從上次中斷的地方繼續執行。

如要在現有叢集上升級 Agent Substrate，請執行安裝程式並選取「Upgrade an installed cluster」。詳情請參閱 substrate-gke README 中的「升級已安裝的叢集」。

選用步驟

部署核心元件後，安裝程式會提供下列選用步驟：

  • Filestore CSI 驅動程式：安裝為 Agent Substrate 設定的 Filestore CSI 驅動程式。如果代理程式需要跨 Pod 共用檔案儲存空間 (例如共用工作區或存放區)，請選擇這個選項。如果叢集已啟用受管理的 GKE Filestore 外掛程式，安裝程式會在部署驅動程式前停用該外掛程式。
  • 節點集區自動調度資源：在節點集區中啟用 GKE叢集自動調度資源。您可以為集區指定節點數下限和上限。如要讓 GKE 在需求量暴增時自動新增節點，並在代理程式暫停時移除節點，請選擇這個選項。如要使用固定節點數量，並預估運算成本，請略過這個選項。
  • 計數器範例：部署範例工作負載，示範代理程式暫停和還原作業。如要在安裝後測試叢集，請選擇這個選項。詳情請參閱「試用 Counter 範例」。

驗證安裝

如要確認安裝成功且核心元件正在執行，請執行下列指令，並確保所有 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 指南中的「將 Pin 集區固定至已安裝的基板版本」。
  • 新節點：安裝程式會標示個別節點，而非節點集區。因此，安裝後新增的任何節點 (即使是安裝程式建立的節點集區)，一開始都不會包含版本標籤。您應為 GKE 節點集區加上標籤，這樣新節點就會自動收到標籤。

試用 Counter 範例

如果安裝程式提示時選擇部署 Counter 示範，您可以觀察 Agent Substrate 的暫停和還原功能。這個範例會執行小型網路伺服器，並將計數值保留在記憶體中。

部署範例的 WorkerPool 和 ActorTemplate 後，安裝程式會列印您需要從 ActorTemplate 建立 Actor 的指令，以及將要求傳送至該 Actor 的指令。上游 Agent Substrate 存放區中的「Counter demo README」說明瞭後續步驟。

解除安裝 Agent Substrate

安裝完成並結束後，安裝程式會列印適用於您環境的自訂清除指令。

如要移除安裝期間建立的資源，請選擇下列任一選項：

  • 從現有叢集移除 Agent Substrate：如果您已在現有叢集上安裝，且想保留叢集和其他工作負載，請只刪除 Agent Substrate 元件，方法是執行安裝程式列印的 ate-setup delete ate-system 指令。安裝程式會預先填入這個指令，並使用安裝期間設定的專案、叢集和位置值。

  • 刪除所有資源 (包括叢集)：如要刪除 GKE 叢集、快照 bucket、IAM 繫結和資訊主頁，請執行安裝程式列印的 cleanup-gcp 指令。安裝程式會預先填入安裝期間設定的專案、叢集、位置和 bucket 值。詳情請參閱 substrate-gke README 的「Tearing down」一節。

後續步驟