このドキュメントでは、エージェントのデータ ライフサイクルのニーズに合わせて、GKE で Agent Sandbox のストレージを管理するためのリファレンス実装について説明します。
エージェントのデータ ライフサイクルのニーズに応じて、次のいずれかの構成を選択します。
ストレージ ソリューションの選択の詳細については、AI エージェント ワークロードのストレージを選択するをご覧ください。
次のドキュメントでは、ディスクタイプの自動選択に dynamic-rwo StorageClass を使用して、GKE Pod の Agent Sandbox がスケジュールされているノードのマシンタイプと互換性のあるディスクをプロビジョニングします。GKE がエージェントのストレージに Hyperdisk Balanced ボリュームをプロビジョニングできるようにするには、互換性のあるマシン ファミリー(N4 など)のノードの GKE Pod で Agent Sandbox をスケジュールする必要があります。そうしないと、GKE は pd-balanced にフォールバックします。
このドキュメントでは、ReadWriteOnce(RWO)アクセスを使用して、プライベート分離ワークスペースのデータアクセス モードを実装します。このモードでは、エージェントは、単独の読み取り / 書き込みアクセス権を持つプライベートな分離ストレージ ディレクトリで起動します。
特に明記されていない限り、このドキュメントのリファレンス実装では、直接サンドボックス作成を使用します。これは、数秒の起動レイテンシを許容するエージェントに適用されます。ステートフル ワークスペースまたはポイントインタイム復元ワークスペースで 1 秒未満の起動レイテンシを実現するには、GKE ウォームプールで Agent Sandbox を使用する必要があります。要求されたウォームプール Pod にストレージをバインドするには、カスタム スクリプトと特権 DaemonSet が必要です。リファレンス実装については、こちらの GitHub の例をご覧ください。
代替アクセスモード
代替アクセスモードをサポートするには、構成でボリュームとスナップショットの定義を変更します。
- 共同作業ワークスペース:
accessModesをReadWriteManyに変更し、RWX 対応の StorageClass(Filestore Multishares(Enterprise)(enterprise-multishare-rwx)など)を使用します。 - 探索ブランチ ワークスペース: テンプレート フォルダを読み取り専用としてマウントし、別の書き込み可能なスクラッチパッドを提供します。ベース テンプレートには、
ReadOnlyMany(ROX)アクセスモードの Hyperdisk ML や RWX アクセスモードの Filestore マルチシェアなど、複数の読み取り専用アタッチメントをサポートするストレージを使用する必要があります。
始める前に
Agent Sandbox コントローラがインストールされている GKE クラスタがあることを確認します。そうでない場合は、GKE に Agent Sandbox をインストールするの次のセクションのみを完了してから、このドキュメントに戻ります。
そのドキュメントのサンドボックス環境をデプロイするセクションを完了している場合は、作成したサンプル リソースを削除して、このドキュメントのサンドボックスに十分な容量をノードに確保します。
kubectl delete sandboxclaim sandbox-claim --ignore-not-found
kubectl delete sandboxwarmpool python-runtime-warmpool --ignore-not-found
kubectl delete sandbox sandbox-example-2 --ignore-not-found
ステートフル ワークスペースを構成する
このパターンは、エージェントのファイルの最新状態を保持するために使用します。これは、エージェント セッションが一時停止または終了したとき(Agent Sandbox が削除されたとき)にエージェントが状態を保持し、エージェント セッションが有効になったとき(Agent Sandbox が再作成されたとき)に最新の状態からデータを復元する必要がある場合に便利です。
このセクションのリファレンス実装では、サンドボックスを直接作成します。これは、数秒の起動レイテンシを許容するエージェントに適用できます。
このアプローチでは、標準の GKE PersistentVolumeClaim(PVC)リソースを使用して、ユーザーのデータを含む既存の PVC にサンドボックスをリンクします。
ステートフル ワークスペース パターンは、次の一連のイベントに従います。
- プロビジョニング: 管理者またはオーケストレーターが、決定論的識別子(
pvc-agent-1など)を使用して、各エージェント セッションのプライベート PVC を手動でプロビジョニングします。 - 参照:
Sandboxリソースで、volumesブロック内のpersistentVolumeClaimフィールドを使用して、既存のボリュームの正確なclaimNameを指定します。 - レイテンシ: サンドボックスが作成されると、GKE は Compute Engine ディスクをノード VM に動的にアタッチする必要があります。これにより、標準で数秒の遅延が発生します。
- 永続性: セッションの終了時(
Sandboxリソースの削除時)に、GKE はディスクを切断しますが、PVC は破棄しません。これにより、次のセッションで最新の状態が保持されます。
セッション間でデータを保持するステートフル ワークスペースを構成するには、次のサブセクションの手順を完了します。
永続ワークスペース(PVC)をプロビジョニングする
pvc-agent-1 などの決定的識別子を使用するプライベート PersistentVolumeClaim(PVC)を作成します。
次のマニフェストを
pvc-agent-1.yamlとして保存します。apiVersion: v1 kind: PersistentVolumeClaim metadata: name: pvc-agent-1 # Derived directly from the deterministic assignment ID namespace: default spec: accessModes: - ReadWriteOnce storageClassName: dynamic-rwo # Selects disk type compatible with the node machine family resources: requests: storage: 10Gi次のようにマニフェストを適用します。
kubectl apply -f pvc-agent-1.yaml
ストレージ クラスは動的ボリューム バインディングを使用するため、ディスクはまだどのノードにもアタッチされていません。リクエストする Pod がスケジュールされるまで、Pending 状態のままになります。
Agent Sandbox をデプロイする
決定論的 PVC を参照して、Sandbox カスタム リソースをデプロイします。
次のマニフェストを
sandbox-agent-1.yamlとして保存します。apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-agent-1 # Traceable sandbox name namespace: default spec: podTemplate: spec: runtimeClassName: gvisor # Required automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace-disk mountPath: /workspace # Mounts the private disk into the container resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace-disk persistentVolumeClaim: claimName: pvc-agent-1 # Binds this specific Sandbox to Agent 1's PVC restartPolicy: OnFailure次のようにマニフェストを適用します。
kubectl apply -f sandbox-agent-1.yamlサンドボックスの準備が整うまで待ちます。
kubectl wait sandbox sandbox-agent-1 \ --for=condition=Ready \ --timeout=300sGKE はノードの容量を確認し、ディスクをアタッチします。これには数秒かかります。コンテナは、ユーザー空間の gVisor カーネル内で初期化されます。Autopilot クラスタでは、GKE がノードを作成する必要があるため、サンドボックスの準備が完了するまでに数分かかることがあります。
エージェントからデータを書き込む
マウントされたディスクにテキスト ファイルを書き込むことで、ワークスペース内でファイル変更を実行するアクティブな AI エージェントをシミュレートします。
# Set the active Pod name
POD_NAME=sandbox-agent-1
# Write a state file to the persistent directory
kubectl exec ${POD_NAME} -- sh -c "echo 'Workspace State Saved - Agent 1' > /workspace/modified_data.txt"
# Confirm the file exists on the disk
kubectl exec ${POD_NAME} -- cat /workspace/modified_data.txt
エージェント セッションを終了する
エージェントがアイドル状態になったときにセッションをスケールダウンまたは終了するシミュレーションを行うには、Sandbox リソースを削除しますが、基盤となるストレージは保持します。
kubectl delete sandbox sandbox-agent-1
GKE はディスクをマウント解除して切断します。pvc-agent-1 PVC は残り、データは保持されます。
エージェント セッションを再開する
セッションを再開するには、同じ PVC を参照する新しい Sandbox リソースを再デプロイし、サンドボックスの準備が整うまで待ちます。
kubectl apply -f sandbox-agent-1.yaml
kubectl wait sandbox sandbox-agent-1 \
--for=condition=Ready \
--timeout=300s
ディスクが再アタッチされ(アタッチの遅延が発生)、コンテナが起動します。
データ保持を確認する
新しく作成されたサンドボックス コンテナを検査して、以前のセッション データが保持されていることを確認します。
# Set the active Pod name of the new session
NEW_POD_NAME=sandbox-agent-1
# Read the file from the newly booted sandbox
kubectl exec ${NEW_POD_NAME} -- cat /workspace/modified_data.txt
出力には Workspace State Saved - Agent 1 が表示されます。
リソースのクリーンアップ
Agent Sandbox と関連する永続ボリューム クレームを削除します。
kubectl delete sandbox sandbox-agent-1
kubectl delete pvc pvc-agent-1
ポイントインタイム復元と所有権の移転を構成する
このパターンは、並列テスト、デバッグ、独立した作業を実行するためにデータセットのクローンを作成する場合に使用します。エージェントのワークスペースは、過去のデータセット(または共有状態)から初期化され、ベース テンプレートを変更することなく、後続の変更を別のプライベートな書き込み可能なレイヤに保存します。
このセクションのリファレンス実装では、サンドボックスを直接作成します。これは、数秒の起動レイテンシを許容するエージェントに適用できます。このアプローチでは、オーケストレーターが、新しいサンドボックス セッションを起動する前に、過去の VolumeSnapshot から新しい PersistentVolumeClaim(PVC)を動的にプロビジョニングします。
VolumeSnapshotClass を作成する
CSI ドライバと削除ポリシーを指定する VolumeSnapshotClass を作成します。Hyperdisk の場合は、pd.csi.storage.gke.io ドライバを使用します。
次のマニフェストを
1-snapshot-class.yamlとして保存します。apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: standard-rwo-snapshot driver: pd.csi.storage.gke.io deletionPolicy: Delete次のようにマニフェストを適用します。
kubectl apply -f 1-snapshot-class.yaml
初期ワークスペースをプロビジョニングする
エージェントが初期作業を行うボリュームを作成します。
次のマニフェストを
2-source-pvc.yamlとして保存します。apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-source-pvc spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo resources: requests: storage: 10Gi次のようにマニフェストを適用します。
kubectl apply -f 2-source-pvc.yaml
状態データを生成する
サンドボックス Pod をデプロイして、ボリュームにデータを書き込みます。
次のマニフェストを
3-source-sandbox.yamlとして保存します。apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: agent-session-v1 namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace persistentVolumeClaim: claimName: agent-source-pvc restartPolicy: OnFailure次のようにマニフェストを適用します。
kubectl apply -f 3-source-sandbox.yamlサンドボックスの準備が整うまで待ってから、状態ファイルを書き込みます。
syncコマンドは、次のセクションのスナップショットにファイルの内容が含まれるように、ディスクへの書き込みをフラッシュします。kubectl wait sandbox agent-session-v1 \ --for=condition=Ready \ --timeout=300s POD_NAME=agent-session-v1 kubectl exec ${POD_NAME} -- sh -c "echo 'Point-in-Time Snapshot - v1' > /workspace/state.txt && sync"
過去の状態をアーカイブする(CSI VolumeSnapshot)
CSI VolumeSnapshot をトリガーして、現在の状態をフリーズします。スナップショットを作成する場合は、ディスク スナップショットのベスト プラクティスに従ってください。
次のマニフェストを
4-volume-snapshot.yamlとして保存します。apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: agent-session-v1-snapshot spec: volumeSnapshotClassName: standard-rwo-snapshot source: persistentVolumeClaimName: agent-source-pvc次のようにマニフェストを適用します。
kubectl apply -f 4-volume-snapshot.yamlスナップショットが使用可能になるまで待ちます。
kubectl wait volumesnapshot agent-session-v1-snapshot \ --for=jsonpath='{.status.readyToUse}'=true \ --timeout=600s
スナップショットからボリュームを復元する
dataSource が CSI VolumeSnapshot を指す新しい PVC をデプロイします。
次のマニフェストを
5-restored-pvc.yamlとして保存します。apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-restored-pvc spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo dataSource: name: agent-session-v1-snapshot kind: VolumeSnapshot apiGroup: snapshot.storage.k8s.io resources: requests: storage: 10Gi次のようにマニフェストを適用します。
kubectl apply -f 5-restored-pvc.yaml
復元された Agent Sandbox セッションを起動する
新しく復元された PVC を参照する新しい Sandbox リソースをプロビジョニングします。
次のマニフェストを
6-restored-sandbox.yamlとして保存します。apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: agent-session-v2-restored namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace persistentVolumeClaim: claimName: agent-restored-pvc restartPolicy: OnFailure次のようにマニフェストを適用します。
kubectl apply -f 6-restored-sandbox.yamlサンドボックスの準備が整うまで待ちます。
kubectl wait sandbox agent-session-v2-restored \ --for=condition=Ready \ --timeout=600sこのサンドボックスは、スナップショットの準備ができた後に GKE がスナップショットからディスクを作成するため、ソース サンドボックスよりも準備に時間がかかることがあります。
永続性と復元を確認する
エージェントが過去のデータを読み取れることを確認します。
NEW_POD_NAME=agent-session-v2-restored
kubectl exec ${NEW_POD_NAME} -- cat /workspace/state.txt
想定される出力: Point-in-Time Snapshot - v1
リソースのクリーンアップ
Agent Sandbox、PVC、VolumeSnapshot を削除します。
kubectl delete sandbox agent-session-v1
kubectl delete sandbox agent-session-v2-restored
kubectl delete pvc agent-source-pvc
kubectl delete pvc agent-restored-pvc
kubectl delete volumesnapshot agent-session-v1-snapshot
kubectl delete volumesnapshotclass standard-rwo-snapshot
エフェメラル ワークスペースを構成する
エージェントがアクティブなときに一時ファイルを保存するためのストレージ ボリュームがエージェントに必要な場合は、エフェメラル ワークスペース パターンを使用します。Agent Sandbox の削除時にデータを保持する必要はありません。
1 秒未満の起動を構成する
GKE ウォームプールで Agent Sandbox を使用して、バックグラウンドで空のボリュームを事前プロビジョニングします。
SandboxTemplate リソースを定義する
volumeClaimTemplate ブロック内でエフェメラル ストレージのバッキングを定義します。
次のマニフェストを
stateless-template.yamlとして保存します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: stateless-sandbox-template namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: ephemeral-disk mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumeClaimTemplates: - metadata: name: ephemeral-disk spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo # Selects disk type compatible with node machine family resources: requests: storage: 10Gi
SandboxWarmPool リソースを起動する
次のマニフェストを
stateless-warmpool.yamlとして保存します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: stateless-warmpool namespace: default spec: replicas: 2 # Keep two standby Pods with pre-attached empty disks sandboxTemplateRef: name: stateless-sandbox-template両方のマニフェストを適用します。
kubectl apply -f stateless-template.yaml kubectl apply -f stateless-warmpool.yamlウォームプールのサンドボックスの準備が整うまで待ちます。
kubectl wait sandboxwarmpool stateless-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sプールのサンドボックスの準備が整う前に
SandboxClaimリソースを作成すると、コントローラはプールからサンドボックスを割り当てるのではなく、クレーム用に新しいサンドボックスを作成することがあります。Autopilot クラスタでは、GKE がノードを作成する必要があるため、サンドボックスの準備が完了するまでに数分かかることがあります。
SandboxClaim リソースを作成する
ユーザーがセッションを開始したときにトリガーされる SandboxClaim リソースを定義します。
次のマニフェストを
stateless-sandbox-claim.yamlとして保存します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: agent-1-claim spec: warmPoolRef: name: stateless-warmpool次のようにマニフェストを適用します。
kubectl apply -f stateless-sandbox-claim.yaml
1 秒未満の実行を検証する
要求の準備が整うまで待ち、Agent Sandbox Pod 名を取得して、/workspace ディレクトリがマウントされ、すぐに使用できる状態であることを確認します。
kubectl wait sandboxclaim agent-1-claim --for=condition=Ready --timeout=300s
export POD_NAME=$(kubectl get sandboxclaim agent-1-claim -o jsonpath='{.status.sandbox.name}')
kubectl exec ${POD_NAME} -- ls -la /workspace
エージェント セッションを終了する
エージェント セッションを終了するには、SandboxClaim リソースを削除します。クレームを削除すると、クレームされたサンドボックスとそのボリュームも削除されます。
kubectl delete sandboxclaim agent-1-claim
リソースのクリーンアップ
SandboxWarmPool リソースと SandboxTemplate リソースを削除します。
kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template
数秒の起動で構成する
数秒のレイテンシを許容するエフェメラル ワークスペースを実装するには、ウォームプールを使用せずに Agent Sandbox を直接作成します。
ステートレス Agent Sandbox を定義する
次のマニフェストを
sandbox-direct-stateless.yamlとして保存します。apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-direct-stateless namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: ephemeral-disk mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required restartPolicy: OnFailure volumeClaimTemplates: - metadata: name: ephemeral-disk spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo resources: requests: storage: 10Gi
Agent Sandbox をデプロイする
ディスクを動的にプロビジョニングして、スケジュールされたノードにアタッチするには、マニフェストを適用します。
kubectl apply -f sandbox-direct-stateless.yaml
起動レイテンシと実行を検証する
Pod のステータスをモニタリングして、Pod が Running 状態に移行する前のアタッチメントの遅延を観察します。
kubectl get pods -w
Pod が実行されたら、Ctrl+C キーを押してモニタリングを停止します。
Pod 名を取得し、/workspace ディレクトリが使用可能であることを確認します。
POD_NAME=sandbox-direct-stateless
kubectl exec ${POD_NAME} -- ls -la /workspace
エージェント セッションを終了する
Sandbox リソースを削除して、Pod を自動的に終了し、エフェメラル ストレージを破棄します。
kubectl delete sandbox sandbox-direct-stateless
次のステップ
- GKE の Agent Sandbox の詳細を確認する。
- GKE で Agent Sandbox を使用して AI コード実行を分離する方法の詳細。
- Pod スナップショットを使用して GKE 環境で Agent Sandbox を保存して復元する方法を学習する。