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

Agent Substrate は、アイドル状態のエージェントを一時停止し、再度動作する必要があるときにエージェントを復元することで、GKE クラスタでエージェント ワークロードを効率的に実行します。Agent Substrate は、GKE Standard クラスタにインストールできるオープンソース ソフトウェアです。

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

料金

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

制限事項

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

  • Cloud Shell: Cloud Shell には 5 GB の永続ディスク ストレージが用意されていますが、インストールには十分ではないため、Cloud Shell に Agent Substrate をインストールすることはできません。インストーラはローカルマシンで実行する必要があります。
  • クラスタモード: Agent Substrate は GKE Standard クラスタにのみインストールできます。Autopilot クラスタはサポートされていません。
  • 既存のクラスタとベータ版 API: 既存のクラスタで必要なベータ版 API（podcertificaterequests と clustertrustbundles）を有効にすることはできません。バージョン 1.36 を実行している既存のクラスタにインストールする場合は、クラスタの作成時にこれらの 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 をクリックしてインストーラを起動します。

  • インストーラはユーザーに代わって API を有効にし、リソースをプロビジョニングするため、次のコマンドを実行してアプリケーションのデフォルト認証情報（ADC）を設定します。

    gcloud auth application-default login

    ADC での認証の詳細については、アプリケーションのデフォルト認証情報を設定するをご覧ください。

必要なロール

Agent Substrate のインストールに必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

クラスタ要件

インストーラにクラスタの作成を任せると、Agent Substrate のすべての要件を満たすクラスタが自動的に構成されます。

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

  • GKE Standard で実行されます（Agent Substrate は Standard クラスタでのみサポートされます）。
  • GKE バージョン 1.36（ベータ版フラグが有効）またはバージョン 1.37 以降を実行している。
  • ノードに c3-standard-4 以上のマシンタイプを使用します。
  • PodCertificateRequest と ClusterTrustBundle Kubernetes API が有効になっている（certificates.k8s.io/v1beta1/podcertificaterequests と certificates.k8s.io/v1beta1/clustertrustbundles）。これらの API は Kubernetes バージョン 1.37 以降で一般提供されています。つまり、バージョン 1.37 以降を実行しているクラスタでは有効になっています。バージョン 1.36 パッチ バージョンを実行している既存のクラスタでのみ、手動で有効にする必要があります。手順については、既存のクラスタでベータ版 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 をインストールするかを選択します。既存のクラスタにインストールする場合は、クラスタ要件セクションの要件を満たしていることを確認します。
  • スナップショット バケット（省略可）: カスタム Cloud Storage バケット名を指定します。空白のままにすると、インストーラによって ate-snapshots-<project>-<zone> という名前のデフォルト バケットが作成されます。

コンテナ イメージのソースを選択するよう求められたら、次のいずれかのオプションを選択します。

  • ビルド済みイメージ: 公開されたイメージをコンテナ レジストリから pull します。ビルドも push も行われないため、 Google Cloud プロジェクトに独自のコンテナ レジストリは必要ありません。
  • ソースからビルド: 上流の Agent Substrate リポジトリ（またはカスタム ブランチ）からイメージをビルドし、プロジェクトの Artifact Registry レジストリに push します。

インストーラの機能

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

  • setup-gcp: 必要な Google Cloud リソースを作成または検証し、API を有効にして、GKE クラスタ（既存のクラスタを使用しない場合）と Cloud Storage バケットを作成し、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 ベータ版 API を有効にして、Agent Substrate コンポーネント間の TLS 通信用の証明書を発行します。
    • マネージド OpenTelemetry: クラスタから指標とトレースを収集します。
  3. Agent Substrate がスナップショットを書き込む Cloud Storage バケットを作成します。
  4. スナップショットを保存するために、Agent Substrate に Cloud Storage へのアクセス権を付与します。ソースからビルドする場合は、コンテナ イメージの Artifact Registry へのアクセス権も付与します。
  5. Agent Substrate のルーティング レイテンシ、スナップショット サイズ、gRPC トラフィックをグラフ化する Cloud Monitoring ダッシュボードを作成します。

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

  1. Agent Substrate API グループとリソースをクラスタに追加します。これらは、ActorTemplate（エージェントが使用するコンテナ イメージとリソースを定義）や WorkerPool（アイドル状態のサンドボックスをいくつ準備しておくかを定義）などの Kubernetes カスタム リソースです。
  2. Agent Substrate のコンポーネントとアクターを識別する証明書を発行する認証局を設定します。コンポーネントは、これらの証明書を提示して、mTLS を使用して相互に認証します。
  3. Agent Substrate のコンポーネントをクラスタにデプロイします。また、アクターとワーカーの状態を追跡する PostgreSQL データベースもデプロイします。インストーラは、データベースとすべてのコントロール プレーン Pod の準備が整うまで待機します。

Agent Substrate は、ate-system Namespace と podcertificate-controller-system Namespace 内の通常のワークロードとしてコンポーネントをデプロイします。インストールでは、GKE コントロール プレーンは変更されません。

デプロイされるコンポーネントには、Agent Substrate がデフォルトで使用する gVisor ベースのランタイムが含まれます。このランタイムは、各エージェントを実行するノードから分離します。インストーラは 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 でノードを自動的に追加し、エージェントが一時停止したときにノードを削除する場合は、このオプションを選択します。コンピューティング費用を予測可能な固定ノード数にする場合は、このオプションをスキップします。
  • カウンタ デモ: エージェントの停止と復元を示すサンプル ワークロードをデプロイします。インストール後にクラスタをテストする場合は、このオプションを選択します。詳細については、カウンタのデモを試すをご覧ください。

インストールを確認する

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

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

ノードのラベル付けとバージョン

インストーラは、クラスタ内のすべてのノードに ate.dev/substrate-version ラベルを適用します。このラベルは、クラスタにインストールされている Agent Substrate のバージョンを指定します。Agent Substrate は、このバージョン ラベルが付いているノードでのみワーカーを実行します。

クラスタにインストールされている Agent Substrate のバージョンを確認するには、次のコマンドを実行します。

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

次のノード ラベルの詳細について検討します。

  • ワーカープール: WorkerPool を作成するときに、このバージョンタグをターゲットにするように構成します。例については、Substrate API ガイドのインストールされている基板バージョンにプールを固定するをご覧ください。
  • 新しいノード: インストーラは、ノードプールではなく個々のノードにラベルを付けます。そのため、インストール後に追加された新しいノード（インストーラによって作成されたノードプール内のノードを含む）は、バージョンラベルなしで起動します。新しいノードにラベルが自動的に付加されるように、GKE ノードプールにラベルを付ける必要があります。

カウンターのデモを試す

インストーラでプロンプトが表示されたときに Counter デモをデプロイすることを選択した場合は、Agent Substrate の一時停止と復元の機能を確認できます。このデモでは、メモリにカウントを保持する小さなウェブサーバーを実行します。

デモの WorkerPool と ActorTemplate をデプロイすると、インストーラは ActorTemplate から Actor を作成し、その Actor にリクエストを送信するために必要なコマンドを出力します。アップストリームの Agent Substrate リポジトリにあるカウンター デモの README に、次の手順が記載されています。

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

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

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

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

  • すべてのリソース（クラスタを含む）を削除する: GKE クラスタ、スナップショット バケット、IAM バインディング、ダッシュボードを削除するには、インストーラが出力する cleanup-gcp コマンドを実行します。インストーラは、インストール時に構成されたプロジェクト、クラスタ、ロケーション、バケットの値をこのコマンドに事前入力します。詳しくは、substrate-gke README の「Tearing down」セクションをご覧ください。

次のステップ