GKE に Agent Substrate をインストールする

GKE 上の Agent Substrate は、GKE クラスタでエージェント ワークロードを効率的に実行します。アプリケーションはアイドル状態のエージェントを一時停止し、システムはエージェントが再び動作する必要があるときに復元します。GKE の Agent Substrate は、GKE Standard クラスタにインストールできるオープンソース ソフトウェアです。GKE 上の Agent Substrate と GKE 上の Agent Sandbox を比較し、AI エージェント ワークロードのアーキテクチャを選択するには、GKE 上の AI エージェント ワークロードのアーキテクチャを計画するをご覧ください。

このドキュメントでは、Agent Substrate on GKE 用に Google Cloud プロジェクトと GKE クラスタを準備する方法、インストーラを実行する方法、インストールによって作成されるリソースについて説明します。

料金

GKE の Agent Substrate は追加料金なしで利用できます。作成したリソースには GKE の料金が適用されます。

制限事項

GKE の Agent Substrate には、次のインストール制限があります。

  • Cloud Shell: Cloud Shell では 5 GB の永続ディスク ストレージが提供されますが、これはインストールには不十分なため、Cloud Shell の GKE に Agent Substrate をインストールすることはできません。インストーラはローカルマシンで実行する必要があります。
  • クラスタモード: GKE に Agent Substrate をインストールできるのは、GKE Standard クラスタのみです。Autopilot クラスタはサポートされていません。
  • クラスタ バージョン: クラスタのコントロール プレーンとノードプールの両方で、GKE バージョン 1.37 以降が実行されている必要があります。1.37 より前のバージョンはサポートされていません。
  • リリース チャンネル: 拡張リリース チャンネルに登録されているクラスタの GKE に Agent Substrate をインストールすることはできません。インストーラはクラスタで Kubernetes ベータ版 API を有効にします。Extended チャンネルは、明示的に有効にされたベータ版 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 ランタイムを提供しません。

  • インストーラがビルドしたイメージを push できるように、クラスタのリージョンで Artifact Registry に対する認証を行うように Docker を構成します。

    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 のすべての要件を満たすクラスタが自動的に構成されます。

既存のクラスタに Agent Substrate on GKE をインストールする場合は、そのクラスタが次の要件を満たしている必要があります。

  • GKE Standard で実行されます（GKE の Agent Substrate は Standard クラスタでのみサポートされています）。
  • コントロール プレーンとノードプールの両方で GKE バージョン 1.37 以降を実行している。コントロール プレーンが以前のバージョンを実行している場合は、まずコントロール プレーンをアップグレードします。次に、以前のバージョンを実行しているノードプールをアップグレードして、ノードが Pod 証明書を Pod にマウントできるようにします。
  • Extended リリース チャンネルに登録されていない。詳細については、制限事項をご覧ください。
  • GKE Dataplane V2 を使用します。
  • ノードに c3-standard-4 以上のマシンタイプを使用します。

  • ノードあたり約 800 個を超えるサンドボックスを同時に実行する予定がある場合、クラスタは、ファイル システム モニタリング（inotify）と Address Resolution Protocol（ARP）のネイバー テーブルに対して Linux カーネルの上限が高いノードを使用します。これらの上限を引き上げないと、サンドボックスが起動せず、ネットワーキングが停止する可能性があります。ノードには、次のカーネル設定が必要です。

    • 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

  • Counter デモをインストールして試すには、次のコマンドを実行します。

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

インタラクティブ インストーラにより、コンテナ イメージ、プロジェクト、クラスタ、ストレージ、Ingress の設定を求められます。インストーラは、可能な場合は推奨されるデフォルトを提案します。これらをそのまま使用することも、カスタマイズすることもできます。

  • コンテナ イメージ（必須）: インストーラでイメージを選択するように求められたら、[ソースからビルド] を選択します。インストーラは、アップストリームの Agent Substrate リポジトリからイメージをビルドし、プロジェクトの Artifact Registry リポジトリに push します。デフォルトでは、インストーラは最新バージョンの Agent Substrate をビルドします。別のバージョンをビルドするには、アップストリーム リポジトリからブランチ、タグ、または完全な commit SHA を入力します。
  • プロジェクト ID（必須）: リソースがプロビジョニングされる Google Cloud プロジェクトを指定します。gcloud CLI のデフォルト プロジェクトを構成している場合、インストーラはそのプロジェクト ID を使用します。
  • クラスタ（必須）: インストーラで推奨されるデフォルトを使用して新しい GKE クラスタを作成するか、既存のクラスタに GKE 上の Agent Substrate をインストールするかを選択します。既存のクラスタにインストールする場合は、クラスタの要件セクションの要件を満たしていることを確認します。
  • スナップショット バケット（省略可）: カスタム Cloud Storage バケット名を指定します。空白のままにすると、インストーラによって ate-snapshots-<project>-<cluster>-<zone> という名前のデフォルト バケットが作成されます。デフォルト名にはクラスタ名が含まれているため、同じプロジェクトとゾーン内のクラスタはバケットを共有しません。インストーラは、名前に -assets サフィックスを追加してアセット バケットも作成します。バケット名は 63 文字以下にする必要があるため、カスタム名は 56 文字以下にする必要があります。デフォルトの名前が 56 文字を超える場合、インストーラは名前を短縮してハッシュを追加します。
  • Ingress クライアント（必須）: アプリケーションのフロントエンド サービスやバックエンド サービスなど、Actor にリクエストを送信するワークロードの SPIFFE ID を入力します。SPIFFE ID は、Namespace と Pod が実行される Kubernetes サービス アカウントによってワークロードを識別します。たとえば、frontend サービス アカウントとして shop Namespace で実行される Pod の SPIFFE ID は spiffe://cluster.local/ns/shop/sa/frontend です。ID は Namespace とサービス アカウントのみに依存するため、まだデプロイしていないクライアントの ID を入力できます。複数の ID はカンマで区切ります。リクエストは Ingress ルーターを介して Actor に到達します。このルーターは、SPIFFE ID がこのリストにある Pod 証明書を提示するクライアントのみを許可します。リスト上のクライアントは、どのアクターにもアクセスできます。--demo フラグを指定すると、インストーラは ID を要求する代わりに、Counter デモの Pod のみを許可します。インストール後にクライアントを追加するには、substrate-gke README の上り（内向き）ルーターを介してアクターにアクセスするをご覧ください。

インストーラの処理

インストーラは、ユーザーに代わって次のプログラムを実行します。

  • 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: 受信リクエストをエージェントにルーティングするために必要なネットワーキングを処理します。
    • マネージド OpenTelemetry: クラスタから指標とトレースを収集します。
  3. GKE の Agent Substrate が使用する Cloud Storage バケットを作成します。1 つはスナップショット用、もう 1 つは microVM ランタイムに必要なファイル用です。2 番目のバケットの名前は、スナップショット バケットの名前の後に -assets サフィックスを付けたものです。
  4. インストーラがビルドするコンテナ イメージ用に ate-images という名前の Artifact Registry リポジトリを作成します。
  5. GKE の Agent Substrate がスナップショットの転送に使用する ate-snapshot-transfer という名前のサービス アカウントを作成します。
  6. GKE ノード、GKE コンポーネントの Agent Substrate、ate-snapshot-transfer サービス アカウントに、バケットとコンテナ イメージにアクセスするために必要な IAM 権限を付与します。
  7. GKE 上の Agent Substrate のルーティング レイテンシ、スナップショット サイズ、gRPC トラフィックをグラフ化する Cloud Monitoring ダッシュボードを作成します。

次に、インストーラはクラスタに次の変更を加えます。

  1. GKE Kubernetes カスタム リソースの Agent Substrate をクラスタに追加します。たとえば、WorkerPool（アイドル状態のサンドボックスの数を定義）や SandboxConfig（サンドボックス ランタイムを定義）などです。ActorTemplate（エージェントが使用するコンテナ イメージとリソースを定義する）やアクターなど、GKE リソース上の他の Agent Substrate は Kubernetes リソースではありません。これらは、kubectl ate プラグイン（Actor と Worker を管理するための kubectl プラグイン）を使用して、Agent Substrate on GKE API を介して管理します。プラグインをインストールするには、kubectl ate プラグインをインストールするをご覧ください。
  2. GKE コンポーネント上の Agent Substrate とアクターを識別する証明書を発行する認証局を設定します。コンポーネントは、これらの証明書を提示して、mTLS を使用して相互に認証します。
  3. GKE コンポーネントの Agent Substrate をクラスタにデプロイし、Actor と Worker の状態を追跡する PostgreSQL データベースもデプロイします。データベースは、500 GiB の永続ディスクにデータを保存します。インストーラは、データベースとすべてのコントロール プレーン Pod の準備が整うまで待機します。本番環境クラスタの場合、インストーラを実行する前に、PostgreSQL データベースとシステム インフラストラクチャ コンポーネントを専用のノードプールに分離できます。手順については、システム インフラストラクチャとワーカー ノードプールを分離するをご覧ください。

GKE の Agent Substrate は、ate-system Namespace と podcertificate-controller-system Namespace 内に通常のワークロードとしてコンポーネントをデプロイします。既存のクラスタにインストールする場合、インストーラはクラスタを更新して、Workload Identity Federation for GKE、Managed OpenTelemetry、podcertificaterequests と clustertrustbundles Kubernetes API のベータ版などの機能がオフになっている場合は、それらを有効にします。ベータ版 API を有効にすると、GKE コントロール プレーンが更新されます。これには約 10 分かかります。

デプロイされるコンポーネントには、GKE 上の Agent Substrate がデフォルトで使用する gVisor ベースのランタイムが含まれます。このランタイムは、各エージェントを実行元のノードから分離するために使用されます。オプションの手順で microVM ランタイムを選択すると、インストーラは microVM ランタイムに必要なファイルを Cloud Storage にアップロードし、それらのファイルを指す microvm という名前のクラスタ全体の SandboxConfig リソースを適用します。

microVM ランタイムを使用するワーカーには、仮想マシンを実行できるノードが必要です。インストーラがクラスタを作成すると、作成されるノードプールでネストされた仮想化が有効になります。[詳細] 設定を選択してマシンタイプを変更する場合は、C3、C4、N2、N4 など、ネストされた仮想化をサポートするマシンシリーズを選択します。

既存のクラスタの GKE に Agent Substrate をインストールする場合、インストーラはクラスタにノードプールを追加しません。microVM ランタイムを使用するには、ネストされた仮想化が有効になっているノードプールか、x86 ベアメタル マシンタイプを使用するノードプールがクラスタに必要です。ネストされた仮想化は、ノードプールの作成時にのみ有効にできます。クラスタにそのようなノードプールがない場合、microVM ランタイムを選択すると、インストーラから警告が表示されます。続行すると、microVM ワーカーは Pending 状態のままになります。taint など、これらのノードプールを構成する方法については、substrate-gke README のサンドボックス ランタイムをご覧ください。

インストールがなんらかの理由（一時的なネットワーク エラーやトークンの有効期限切れなど）で失敗した場合は、コマンドを再実行します。インストーラは既存のリソースを保持し、中断したところから再開します。

GKE にインストールされている Agent Substrate をアップグレードするには、インストーラを実行して [Upgrade an installed cluster] を選択します。このオプションでは、クラスタは変更されません。代わりに、インストーラは、インストールされているバージョンとアップグレードするバージョンのソースコードをダウンロードし、アップグレード ランブックで使用する ~/ate-upgrade ディレクトリを準備します。アップグレードを実行するには、インストーラが出力するコマンドを実行し、アップストリームの Agent Substrate リポジトリのアップグレード ランブックの最初の手順から実行します。この Runbook は、同じマイナー バージョンの新しいパッチリリースへのアップグレードをサポートしています。バージョン 1.0 以降では、次のマイナー バージョンへのアップグレードもサポートしています。1.0 より前のバージョンでは、新しいマイナー バージョンに移行するには再インストールが必要です。詳細については、substrate-gke README のインストール済みクラスタのアップグレードをご覧ください。

省略可能な手順

コア コンポーネントをデプロイすると、インストーラは次のオプションの手順を提示します。

  • Filestore CSI ドライバ: GKE の Agent Substrate 用に構成された Filestore CSI ドライバをインストールします。エージェントが別のノードで再開したときに使用可能な永続ストレージがエージェントに必要な場合は、このオプションを選択します。各エージェントには独自のストレージがあり、他のエージェントとは共有されません。Filestore エージェント ボリュームのプロダクション サポートは限定 GA であるため、アクセスをリクエストする必要があります。詳細については、GKE で Agent Substrate を使用して Filestore エージェント ボリュームを使用するをご覧ください。クラスタでマネージド GKE Filestore アドオンが有効になっている場合、インストーラはドライバをデプロイする前にアドオンを無効にします。インストーラは、gcp-filestore-csi-driver Namespace にドライバをデプロイし、ドライバに必要な IAM 権限を持つ substrate-filestore-csi という名前のサービス アカウントを作成します。
  • ノードプールの自動スケーリング: ノードプールで GKE クラスタの自動スケーリングを有効にします。プールのノードの最小数と最大数を指定します。需要の急増時に GKE が自動的にノードを追加し、エージェントが一時停止したときにノードを削除する場合は、このオプションを選択します。コンピューティング費用を予測できる固定ノード数を希望する場合は、このオプションをスキップします。カスタム ComputeClass、スタンバイ容量バッファ、アクティブな Actor のスケールダウン保護を使用して自動ハードウェア フォールバックを構成するには、GKE 上の Agent Substrate のインフラストラクチャを設計するをご覧ください。
  • サンドボックス ランタイム: エージェントを分離するランタイムを選択できます。インストーラは、コア コンポーネントの一部として gVisor ランタイムをインストールするため、gVisor ランタイムに追加の構成は必要ありません。ハードウェア仮想化を使用する分離が必要な場合は、microVM ランタイムを選択します。既存のクラスタでこのオプションを選択する前に、クラスタにネストされた仮想化が有効になっているノードプールがあるか、x86 ベアメタル マシンタイプを使用していることを確認してください。詳細については、インストーラの処理をご覧ください。
  • カウンタのデモ: エージェントの停止と復元を示すサンプル ワークロードをデプロイします。このステップは、インストーラの起動時に --demo フラグを指定した場合にのみ表示されます。インストール後にクラスタをテストする場合は、このオプションを選択します。詳細については、Counter デモを試すをご覧ください。

インストールを確認する

インストールが成功し、コア コンポーネントが実行されていることを確認するには、次のコマンドを実行して、すべての Pod のステータスが Running であることを確認します。

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

kubectl ate プラグインをインストールする

アクターと 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 ディレクトリにプラグインを配置します。kubectl ツールは、そのディレクトリが PATH 環境変数にある場合にのみプラグインを検出します。PATH 環境変数にそのディレクトリが含まれていない場合は、kubectl ate コマンドを実行する前に追加します。

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

Counter のデモを試す

インストーラを実行するときに --demo フラグを指定し、Counter デモをデプロイすることを選択した場合、インストーラは、メモリとファイル内のリクエストをカウントするウェブサーバーに WorkerPool と ActorTemplate をデプロイします。GKE の Agent Substrate は、サーバーを実行する Actor を一時停止して復元するときに、両方のカウントを保持します。

インストールが完了すると、インストーラはデモの次のステップ（kubectl ate プラグインをインストールするコマンドと、ActorTemplate から Actor を作成するコマンド）を出力します。kubectl ate コマンドを実行する前に、kubectl ate プラグインをインストールするの説明に沿って、プラグインが PATH 環境変数に設定されていることを確認します。

インストーラは、Actor にリクエストを送信するコマンドを出力しません。Ingress ルーターは、SPIFFE ID が許可リストにある Pod 証明書を提示するクライアントのみを許可するため、ローカルマシンから直接送信されたリクエストは拒否されます。デモの詳細については、インストーラがデフォルトでデプロイする Agent Substrate バージョン 1.0.0 のカウンタデモの README をご覧ください。インストーラが設定したクラスタでは、同じ理由で、ポート転送を介してリクエストを送信する README の手順は機能しません。

GKE で Agent Substrate をアンインストールする

インストールが完了して終了すると、インストーラは環境に合わせてカスタマイズされたクリーンアップ コマンドを出力します。

インストール中に作成されたリソースを削除するには、次のいずれかのオプションを選択します。

  • 既存のクラスタから GKE 上の Agent Substrate を削除する: 既存のクラスタにインストールし、クラスタとそのワークロードを保持する場合は、インストーラが出力する ate-setup delete ate-system コマンドを実行して、GKE 上の Agent Substrate コンポーネントのみを削除します。インストーラは、インストール中に構成されたプロジェクト、クラスタ、ロケーションの値を使用して、このコマンドを事前入力します。

  • すべてのリソース（クラスタを含む）を削除する: 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 README の「破棄」セクションをご覧ください。

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 に置き換えます。

次のステップ