Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

Standard

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 の永続ディスクストレージが用意されていますが、インストールには十分ではないため、Cloud Shell に GKE 上の Agent Substrate をインストールすることはできません。ローカルマシンでインストーラを実行する必要があります。
クラスタモード: GKE 上の Agent Substrate は、 GKE Standard クラスタにのみインストールできます。 Autopilot クラスタはサポートされていません。
既存のクラスタとベータ版 API: バージョン 1.36 を実行する既存のクラスタで必要なベータ版 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 ロールの付与を管理者に依頼してください。

Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）
Kubernetes Engine 管理者（roles/container.admin）
ストレージ管理者（roles/storage.admin）
プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
Monitoring 編集者（roles/monitoring.editor）

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

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

クラスタ要件

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

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

GKE Standard で実行される（GKE 上の 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 を有効にするには、次のコマンドを実行します。
```
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 上の 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 をインストールするかを選択します。既存のクラスタにインストールする場合は、クラスタ要件セクションの要件を満たしていることを確認してください。

スナップショットバケット（省略可）: カスタムの Cloud Storage バケット名を指定します。空白のままにすると、インストーラによってデフォルトバケット（名前は ate-snapshots-<project>-<zone>）が作成されます。

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

ビルド済みイメージ: Container Registry から公開されたイメージを pull します。何もビルドまたは push されないため、 Google Cloud プロジェクトに独自の Container Registry は必要ありません。

ソースからビルド: 上流の Agent Substrate リポジトリ（またはカスタムブランチ）からイメージをビルドし、プロジェクトの Artifact Registry レジストリに push します。

インストーラの動作

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

setup-gcp: 必要な Google Cloud リソースを作成または検証し、 API を有効にし、GKE クラスタ（既存のクラスタを使用しない場合）と Cloud Storage バケットを作成し、 IAM ポリシーを構成します。
ate-setup: ビルド済みの GKE 上の Agent Substrate コンテナイメージとコントローラを GKE クラスタにデプロイします。

まず、インストーラは Google Cloud プロジェクトに次の変更を加えます。

GKE 上の Agent Substrate に必要な Google Cloud API を有効にします。
次の設定で GKE Standard クラスタを作成します（既存のクラスタを使用しない場合）。
- Workload Identity Federation for GKE: GKE 上の Agent Substrate がノードに鍵を保存せずに Cloud Storage にアクセスできるようにします。
- GKE Dataplane V2: エージェントに着信リクエストをルーティングするために必要なネットワーキングを処理します。
- 証明書 API（PodCertificateRequest と ClusterTrustBundle）: これらの Kubernetes ベータ版 API を有効にして、 GKE 上の Agent Substrate コンポーネント間の TLS 通信の証明書を発行します。
- マネージド OpenTelemetry: クラスタから指標とトレースを収集します。
GKE 上の Agent Substrate がスナップショットを書き込む Cloud Storage バケットを作成します。
スナップショットを保存するために、GKE 上の Agent Substrate に Cloud Storage へのアクセス権を付与します。ソースからビルドする場合は、コンテナイメージの Artifact Registry へのアクセス権も付与します。
GKE 上の Agent Substrate のルーティングレイテンシ、スナップショットサイズ、gRPC トラフィックをグラフ化する Cloud Monitoring ダッシュボードを作成します。

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

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

GKE 上の Agent Substrate は、ate-system 名前空間と podcertificate-controller-system 名前空間内の通常のワークロードとしてコンポーネントをデプロイします。インストールによって GKE コントロールプレーンが変更されることはありません。

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

インストールを確認する

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

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

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

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

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

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

ノードのラベル付けの詳細について考えてみましょう。

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

カウンタデモを試す

インストーラからプロンプトが表示されたときにカウンタデモをデプロイすることを選択した場合は、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 クラスタ、スナップショットバケット、IAM バインディング、ダッシュボードを削除するには、インストーラが出力する cleanup-gcp コマンドを実行します。インストーラは、インストール時に構成されたプロジェクト、クラスタ、ロケーション、バケットの値を使用して、このコマンドを事前入力します。詳細については、 substrate-gke README の「Tearing down」セクションをご覧ください。

次のステップ

GKE 上の Agent Substrate の詳細については、 GKE 上の Agent Substrate についてをご覧ください。

GKE に Agent Substrate をインストールする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

料金