Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

在 GKE 上安裝 Agent Substrate

標準

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

本文件說明如何為 GKE 上的 Agent Substrate 準備 Google Cloud 專案和 GKE 叢集、如何執行安裝程式，以及安裝作業建立的資源。

定價

GKE 上的 Agent Substrate 無須額外付費。您建立的資源會套用 GKE 定價。

限制

在 GKE 上安裝 Agent Substrate 時，有下列限制：

Cloud Shell：Cloud Shell 提供 5 GB 的永久磁碟儲存空間，不足以安裝 Agent Substrate，因此無法在 Cloud Shell 的 GKE 上安裝 Agent Substrate。您必須在本機電腦上執行安裝程式。
叢集模式：您只能在 GKE Standard 叢集上安裝 Agent Substrate。不支援 Autopilot 叢集。
現有叢集和 Beta 版 API：如果在執行 1.36 版的現有叢集上啟用必要的 Beta 版 API (podcertificaterequests 和 clustertrustbundles)，則必須先更換現有節點，才能在 GKE 上安裝 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 進行驗證，請參閱「設定應用程式預設憑證」。

必要的角色

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

服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
Kubernetes Engine 管理員 (roles/container.admin)
儲存空間管理員 (roles/storage.admin)
專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
Monitoring 編輯者 (roles/monitoring.editor)

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

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

叢集需求

如果讓安裝程式為您建立叢集，系統會自動設定叢集，確保符合 GKE 上 Agent Substrate 的所有需求。

如果選擇在現有叢集上安裝 Agent Substrate on GKE，該叢集必須符合下列需求：

在 GKE Standard 上執行 (GKE 上的 Agent Substrate 僅支援 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 後，您必須替換現有節點，例如升級節點集區或重新建立節點。更新前就存在的節點 (MountVolume.SetUp failed: unimplemented) 未啟用 Pod 憑證投影功能。
- 1.37 以上版本：現有節點已啟用 Pod 憑證投影功能，因此啟用 API 後，您不需要更換節點。

在 GKE 安裝 Agent Substrate

如要在 GKE 上安裝 Agent Substrate，請在本機終端機中執行下列指令：

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

互動式安裝程式會提示您輸入專案、叢集和儲存空間設定。系統會盡可能建議預設值，您可以接受或自訂：

專案 ID (必要)：指定要佈建資源的 Google Cloud 專案。如果您已為 gcloud CLI 設定預設專案，安裝程式會使用該專案 ID。
叢集 (必要)：選擇是否要讓安裝程式使用建議的預設值建立新的 GKE 叢集，或是在現有叢集中的 GKE 上安裝 Agent Substrate。如果選擇安裝在現有叢集上，請確認叢集符合「叢集需求」一節中的規定。
快照 bucket (選用)：指定自訂 Cloud Storage bucket 名稱，或留空讓安裝程式建立名為 ate-snapshots-<project>-<zone> 的預設 bucket。

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

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

安裝程式的用途

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

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

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

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

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

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

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

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

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

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

選擇性步驟

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

Filestore CSI 驅動程式：安裝為 GKE 上的 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 on GKE 版本，而 Agent Substrate on GKE 只會在具有這個版本標籤的節點上執行 Worker。

如要查看叢集上安裝的 Agent Substrate on GKE 版本，請執行下列指令：

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

請留意下列節點標籤詳細資料：

worker 集區：建立 WorkerPool 時，請將其設為指定這個版本標記。如需範例，請參閱 Substrate API 指南中的「將集區固定至已安裝的 Substrate 版本」。
新節點：安裝程式會標示個別節點，而非節點集區。因此，安裝後新增的任何節點 (即使是在安裝程式建立的節點集區中) 都不會有版本標籤。您應為 GKE 節點集區加上標籤，這樣新節點就會自動收到標籤。

試用 Counter 範例

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

部署範例的 WorkerPool 和 ActorTemplate 後，安裝程式會列印您需要從 ActorTemplate 建立 Actor 的指令，以及將要求傳送至該 Actor 的指令。請參閱上游 Agent Substrate 存放區中的計數器示範 README，瞭解後續步驟。

在 GKE 解除安裝 Agent Substrate

安裝完成並結束後，安裝程式會輸出環境專屬的清除指令。

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

從現有叢集移除 GKE 上的 Agent Substrate：如果您已在現有叢集上安裝，且想保留叢集和其他工作負載，請執行安裝程式列印的 ate-setup delete ate-system 指令，只刪除 GKE 上的 Agent Substrate 元件。安裝程式會預先填入這個指令，並在安裝期間設定專案、叢集和位置值。
刪除所有資源 (包括叢集)：如要刪除 GKE 叢集、快照 bucket、IAM 繫結和資訊主頁，請執行安裝程式輸出的 cleanup-gcp 指令。安裝程式會預先填入這項指令，其中包含安裝期間設定的專案、叢集、位置和 bucket 值。詳情請參閱 substrate-gke README 的「Tearing down」一節。

後續步驟

如要進一步瞭解 GKE 上的 Agent Substrate，請參閱「關於 GKE 上的 Agent Substrate」。