このドキュメントでは、Google Kubernetes Engine（GKE）クラスタにオープンソースの Agent Sandbox コントローラをインストールして、専用の Kubernetes Pod でサンドボックス化されたワークロードを実行する方法について説明します。また、信頼できないコードを安全に実行するために、クラスタにサンドボックス環境を作成する方法についても説明します。
GKE の Agent Sandbox が信頼できない AI 生成コードを分離する方法の概要については、GKE の Agent Sandbox についてをご覧ください。
Pod ベースのアーキテクチャとアクターベースのアーキテクチャのどちらかを選択する
GKE に Agent Sandbox をインストールする前に、AI エージェント ワークロードに適した GKE アーキテクチャを確認します。
- GKE 上の Agent Substrate（アクターベース）: ほとんどのエージェント ワークロード、特に頻繁に一時停止と再開を行うステートフル エージェントには、このアーキテクチャを使用します。アクティブなエージェントは、エージェントごとに専用の Pod を保持するのではなく、ウォーム Pod のプールを共有するため、より少ないノードでより多くのエージェントを実行できます。GKE の Agent Substrate は、アイドル状態のワークロードを自動的に一時停止して再開し、1 秒未満でストレージからエージェントを復元します。一方、GKE の Agent Sandbox では、手動で Pod のスナップショットを作成する必要があります。また、非アクティブ状態を検出してエージェントの進行状況を保存するアプリケーション コードを構築する必要があります。GKE 上の Agent Substrate には、GKE Standard クラスタが必要です。詳細については、GKE の Agent Substrate についてをご覧ください。このオプションをインストールするには、GKE に Agent Substrate をインストールするをご覧ください。
- GKE 上の Agent Sandbox（Pod ベース）: このドキュメントでインストールするこのアーキテクチャは、各エージェントに GKE Autopilot クラスタまたは Standard クラスタ上の専用の Kubernetes Pod が必要な場合に使用します。継続的にアクティブなエージェントや、次のいずれかを必要とするワークロードには、このオプションを選択します。
- 宣言型 Kubernetes API（
Sandboxカスタム リソースやSandboxClaimカスタム リソースなど） - カスタム サイドカーと init コンテナを含む、完全な Kubernetes
PodSpecスキーマ - GPU や TPU などのハードウェア アクセラレータへの直接アクセス
- GKE Autopilot クラスタ
- 宣言型 Kubernetes API（
費用
GKE の Agent Sandbox は、追加料金なしで使用できるオープンソース ソフトウェアです。作成したリソース（Agent Sandbox コントローラが使用するコンピューティング リソースなど）には、GKE の料金が適用されます。
不要な料金が発生しないように、このドキュメントの完了後に GKE を無効にするか、プロジェクトを削除してください。
始める前に
-
Google Cloud コンソールのプロジェクト セレクタページで、 Google Cloud プロジェクトを選択または作成します。
プロジェクトの選択または作成に必要なロール
- プロジェクトを選択する: プロジェクトを選択する際に、特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトを選択できます。
-
プロジェクトを作成する: プロジェクトを作成するには、
resourcemanager.projects.create権限を含むプロジェクト作成者のロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。
Google Kubernetes Engine API が有効になっていない場合は、有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。-
Google Cloud コンソールで Cloud Shell をアクティブにします。
環境変数を定義する
このドキュメントで実行するコマンドを簡略化するために、Cloud Shell で環境変数を設定できます。Cloud Shell で、次のコマンドを実行して環境変数を定義します。
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v1.0.6"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"
これらの環境変数の説明は次のとおりです。
CLUSTER_NAME: GKE クラスタの名前（例:agent-sandbox-cluster）。LOCATION: GKE クラスタが作成される Google Cloud リージョンまたはゾーン。Autopilot クラスタを作成する場合は、これをリージョン（us-central1など）に設定します。Autopilot クラスタは常にリージョン クラスタです。Standard クラスタを作成する場合は、これをゾーン（us-central1-aなど）に設定します。費用を削減するため、このドキュメントでは、リージョン クラスタよりも使用するノードが少ないゾーンクラスタを作成します。AGENT_SANDBOX_VERSION: インストールするオープンソースの Agent Sandbox コントローラのバージョン。このドキュメントでは、バージョン 1.0.6 を使用します。他のバージョンを確認するには、Agent Sandbox のリリースページをご覧ください。NODE_POOL_NAME: サンドボックス化されたワークロードを実行するノードプールの名前（例:agent-sandbox-pool）。この変数は、GKE Standard クラスタを作成する場合にのみ必要です。MACHINE_TYPE: クラスタのデフォルト ノードプールと gVisor ノードプール内のノードのマシンタイプ（例:e2-standard-2）。さまざまなマシンシリーズとさまざまなオプションの選択の詳細については、マシン ファミリーのリソースと比較ガイドをご覧ください。この変数は、GKE Standard クラスタを作成する場合にのみ必要です。
GKE クラスタを作成する
GKE の Agent Sandbox は、gVisor または microVMs を使用して、サンドボックス化されたワークロードを分離します。サンドボックス ランタイムを指定しない場合、サンドボックスはカーネル分離なしで実行されます。これは、信頼できないコードにはおすすめしません。このドキュメントでは gVisor を使用します。Autopilot クラスタでは、gVisor が自動的に有効になります。Standard クラスタでは、gVisor が有効になっているノードプールを作成します。代わりに microVM を使用するには、microVM サンドボックス タイプを有効にするをご覧ください。推奨されるセキュリティ ポリシーでは gVisor のみが許可されるため、microVM を使用するサンドボックスは拒否されます。
Autopilot
Autopilot クラスタを作成するには、LOCATION 環境変数がリージョン（us-central1 など）に設定されていることを確認してから、次のコマンドを実行します。
gcloud container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION}
Standard
Standard クラスタを作成するには、クラスタを作成してから、gVisor が有効になっているノードプールを追加します。費用を削減するため、このドキュメントでは、プールごとに 1 つのノードを持つゾーンクラスタを作成します。
LOCATION環境変数をゾーン（us-central1-aなど）に設定します。export LOCATION="us-central1-a"クラスタを作成します。
gcloud container clusters create ${CLUSTER_NAME} \ --location=${LOCATION} \ --machine-type=${MACHINE_TYPE} \ --num-nodes=1gVisor を有効にして、独立したノードプールを作成します。
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --machine-type=${MACHINE_TYPE} \ --location=${LOCATION} \ --num-nodes=1 \ --image-type=cos_containerd \ --sandbox=type=gvisorgVisor の代わりに microVM を使用するには、microVM サンドボックス タイプを有効にするの説明に沿ってノードプールを作成します。このドキュメントの残りの部分では、gVisor を使用します。
代わりに既存の Standard クラスタを使用する場合は、クラスタに gVisor が有効になっているノードプールが含まれていることを確認します。クラスタにそのようなノードプールがない場合は、上記の gcloud container node-pools create コマンドを実行して作成します。
kubectl コマンドライン ツールがクラスタに接続できるように、クラスタの認証情報を取得します。
gcloud container clusters get-credentials ${CLUSTER_NAME} \
--location=${LOCATION}
Agent Sandbox をインストールする
Agent Sandbox をインストールするには、Agent Sandbox GitHub リポジトリからリリース マニフェストを適用します。sandbox-with-extensions.yaml マニフェストは、Agent Sandbox コントローラと、Sandbox リソース、SandboxTemplate、SandboxClaim、SandboxWarmPool 拡張リソースの CustomResourceDefinition をインストールします。
リリース マニフェストを適用します。
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yamlこのマニフェストは、
agent-sandbox-systemNamespace を作成し、その Namespace にコントローラをデプロイします。コントローラの準備が整うまで待ちます。
kubectl rollout status deployment/agent-sandbox-controller \ --namespace=agent-sandbox-system \ --timeout=120s
Helm を使用して Agent Sandbox をインストールすることもできます。手順については、Agent Sandbox Helm チャートの README をご覧ください。
インストールを確認する
Agent Sandbox CustomResourceDefinition がインストールされていることを確認します。
kubectl get crd \ sandboxes.agents.x-k8s.io \ sandboxtemplates.extensions.agents.x-k8s.io \ sandboxclaims.extensions.agents.x-k8s.io \ sandboxwarmpools.extensions.agents.x-k8s.io出力には、4 つの CustomResourceDefinition が表示されます。
コントローラが実行されていることを確認します。
kubectl get deployment agent-sandbox-controller \ --namespace=agent-sandbox-systemコントローラが実行されている場合、
READY列に1/1と表示されます。
推奨されるセキュリティ ポリシーを適用する
デフォルトでは、GKE の Agent Sandbox は、サンドボックスを実行する Pod の構成を制限しません。サンドボックスの分離設定を適用するには、Agent Sandbox GitHub リポジトリから推奨される secure-sandbox-policy
ValidatingAdmissionPolicy を適用します。このポリシーは、GKE での Agent Sandbox のデプロイ要件を満たしていない Sandbox リソースを拒否します。
ポリシーを適用します。
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/examples/policy/vap/secure-sandbox-policy.yamlポリシー バインディングを適用します。このバインディングにより、
kube-systemなどのシステム Namespace を除くすべての Namespace にポリシーが適用されます。kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/examples/policy/vap/secure-sandbox-binding.yaml
このポリシーは Sandbox リソースを検証します。SandboxWarmPool リソースまたは SandboxClaim リソースを作成すると、コントローラは SandboxTemplate リソースから Sandbox リソースを作成します。テンプレートが要件を満たしていない場合、ポリシーは Sandbox リソースを拒否し、コントローラ ログにエラーが表示されます。ログを表示するには、次のコマンドを実行します。
kubectl logs deployment/agent-sandbox-controller \
--namespace=agent-sandbox-system
このポリシーはユーザーが所有し、ワークロードに合わせて変更できます。詳細については、サンドボックスのセキュリティ ポリシーをご覧ください。
GKE での Agent Sandbox のデプロイ要件
推奨されるセキュリティ ポリシーを適用する場合、Sandbox リソースや SandboxTemplate リソースなどのワークロード マニフェストに、特定のセキュリティ設定と構成設定を含める必要があります。Sandbox リソースがこれらの要件を満たしていない場合、アドミッション コントローラはリソースを拒否します。コンテナの要件は、初期コンテナやエフェメラル コンテナなど、Pod 内のすべてのコンテナに適用されます。
必要な構成
デプロイ マニフェストには、次の設定を含める必要があります。
runtimeClassName: gvisor: Pod が gVisor サンドボックスで実行されるようにします。このポリシーは、microVM を含む他のランタイムを使用するサンドボックスを拒否します。automountServiceAccountToken: false: Pod がデフォルトのサービス アカウント トークンを自動的にマウントしないようにします。securityContext.runAsNonRoot: true: コンテナが root ユーザーとして実行されないようにします。securityContext.capabilities.drop: ["ALL"]: コンテナからすべての Linux 機能を削除します。resources.limits: サービス拒否（DoS）攻撃の可能性を防ぐために、CPU とメモリの上限を指定する必要があります。nodeSelector:sandbox.gke.io/runtime: gvisorをターゲットにする必要があります。tolerations:sandbox.gke.io/runtime=gvisor:NoScheduletaint の toleration を含める必要があります。
禁止されている構成
デプロイ マニフェストに次のいずれも含めてはなりません。
hostNetwork: true、hostPID: true、またはhostIPC: true。- コンテナ セキュリティ コンテキストの
privileged: true。 - コンテナ セキュリティ コンテキストの
procMount: Unmasked。 HostPathボリューム。- 追加された機能（
capabilities.add）。 hostPortの設定。- カスタム sysctl。
- サービス アカウント トークンまたは証明書の投影ボリューム。
サンドボックス ルーターをデプロイする（省略可）
サンドボックス ルーターは、Agent Sandbox Python クライアントなどのクライアントからのリクエストを、サンドボックスを実行する Pod に転送する HTTP プロキシです。GKE で Agent Sandbox を使用して AI コード実行を分離するで説明されているように、Python クライアントを使用する場合は、ルーターをデプロイします。
ルーターを agent-sandbox-system Namespace にデプロイします。デフォルトでは、GKE の Agent Sandbox が各 SandboxTemplate リソースに作成するネットワーク ポリシーは、この Namespace 内のルーター Pod からのサンドボックスへの受信トラフィックのみを許可します。
ルーターのサービス アカウントと、ルーターがサンドボックス Pod を検索できるようにする RBAC 権限を作成します。
kubectl apply \ -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/serviceaccount.yaml \ -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/rbac.yamlルーターをデプロイします。次のコマンドは、ルーター イメージをコントローラと同じバージョンに設定します。
curl -sSL https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/deployment.yaml \ | sed "s|sandbox-router-go:latest|sandbox-router-go:${AGENT_SANDBOX_VERSION}|" \ | kubectl apply -f -ルーターの Service を作成します。
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/service.yamlルーターの準備が整うまで待ちます。
kubectl rollout status deployment/sandbox-router \ --namespace=agent-sandbox-system \ --timeout=120s
このルーター構成は開発とテスト用です。TLS、レプリカ数、ルーターのネットワーク ポリシーなどの本番環境の設定については、サンドボックス ルーターのデプロイの README をご覧ください。
サンドボックス環境をデプロイする
SandboxTemplate リソースを定義してサンドボックス環境をデプロイし、SandboxWarmPool リソースを使用して、事前にウォームアップされたインスタンスを準備しておくことをおすすめします。SandboxClaim リソースを使用して、このウォームプールからインスタンスをリクエストできます。または、Sandbox リソースを直接作成することもできますが、このアプローチではウォームプールはサポートされません。
SandboxTemplate、SandboxWarmPool、SandboxClaim、Sandbox は Kubernetes カスタム リソースです。
推奨: SandboxTemplate リソースと SandboxWarmPool リソースを作成する
SandboxTemplate リソースは、再利用可能なブループリントとして機能します。SandboxWarmPool リソースは、指定された数の事前にウォームアップされたサンドボックスが常に実行され、要求される準備ができていることを保証します。このカスタム リソースを使用すると、起動レイテンシを最小限に抑えることができます。
SandboxTemplate リソースと SandboxWarmPool リソースを作成してサンドボックス環境をデプロイするには、次の手順を完了します。
Cloud Shell で、次の内容を含むファイルを
sandbox-template.yamlという名前で作成します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: python-runtime-template namespace: default spec: podTemplate: metadata: labels: sandbox-type: python-runtime spec: runtimeClassName: gvisor # Required automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: runtime image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required restartPolicy: OnFailureSandboxTemplateマニフェストを適用します。kubectl apply -f sandbox-template.yaml次の内容で
sandbox-warmpool.yamlという名前のファイルを作成します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: python-runtime-warmpool namespace: default labels: app: python-runtime-warmpool spec: replicas: 2 sandboxTemplateRef: # This must match the name of the SandboxTemplate. name: python-runtime-templateSandboxWarmPoolマニフェストを適用します。kubectl apply -f sandbox-warmpool.yamlウォームプールのサンドボックスの準備が整うまで待ちます。
kubectl wait sandboxwarmpool python-runtime-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sプールのサンドボックスの準備が整う前に
SandboxClaimリソースを作成すると、コントローラはプールからサンドボックスを割り当てるのではなく、クレーム用に新しいサンドボックスを作成することがあります。Autopilot クラスタでは、GKE がノードを作成する必要があるため、サンドボックスの準備が完了するまでに数分かかることがあります。
SandboxClaim リソースを作成する
SandboxClaim リソース リクエストは、ウォームプールからサンドボックスをリクエストします。ウォームプールを作成したため、コントローラは新しいサンドボックスを作成するのではなく、プールから実行中のサンドボックスをクレームに割り当てます。
SandboxClaim リソースを作成してウォームプールからサンドボックスをリクエストするには、次の操作を行います。
次の内容で
sandbox-claim.yamlという名前のファイルを作成します。apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: sandbox-claim namespace: default spec: warmPoolRef: # This must match the name of the SandboxWarmPool. name: python-runtime-warmpoolSandboxClaimマニフェストを適用します。kubectl apply -f sandbox-claim.yamlサンドボックス、クレーム、ウォームプールが準備できていることを確認します。
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
代替方法: Sandbox リソースを直接作成する
ウォームプールによる高速起動時間が不要な場合は、テンプレートを使用せずに Sandbox リソースを直接デプロイできます。
Sandbox リソースを直接作成してサンドボックス環境をデプロイする手順は次のとおりです。
次の内容で
sandbox.yamlという名前のファイルを作成します。apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-example-2 spec: podTemplate: metadata: labels: sandbox: sandbox-example spec: runtimeClassName: gvisor restartPolicy: OnFailure automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 # Required if image defaults to root (for example, busybox) nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: my-container image: busybox command: ["/bin/sh", "-c"] args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"] securityContext: capabilities: drop: ["ALL"] # Required allowPrivilegeEscalation: false resources: limits: cpu: "100m" memory: "128Mi" # RequiredSandboxマニフェストを適用します。kubectl apply -f sandbox.yamlサンドボックスが実行されていることを確認します。
kubectl get sandbox
Agent Sandbox をアップグレードする
Agent Sandbox をアップグレードするには、新しいバージョンのリリース マニフェストを適用します。
export AGENT_SANDBOX_VERSION="NEW_VERSION"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml
NEW_VERSION は、インストールするバージョン（Agent Sandbox のリリース ページに記載されているバージョンなど）に置き換えます。
アップグレードする前に、新しいバージョンのリリースノートを確認してください。クラスタで 1.0.0 より前のバージョンの Agent Sandbox が実行されている場合は、アップグレードする前にリソースを v1beta1 API に移行する必要があります。これは、バージョン 1.0.0 で v1alpha1 API が削除されたためです。手順については、API 移行ガイドをご覧ください。
Sandbox Router をデプロイした場合、または推奨されるセキュリティ ポリシーを適用した場合は、新しいバージョンでこれらの手順を繰り返します。
Agent Sandbox をアンインストールする
まだ使用中の Agent Sandbox リソースを確認します。
kubectl get sandboxes,sandboxclaims,sandboxwarmpools,sandboxtemplates \ --all-namespaces推奨されるセキュリティ ポリシーを適用した場合は、ポリシー バインディングとポリシーを削除します。
kubectl delete validatingadmissionpolicybinding secure-sandbox-binding kubectl delete validatingadmissionpolicy secure-sandbox-policyサンドボックス ルーターをデプロイした場合は、クラスタ全体の RBAC リソースを削除します。
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/rbac.yamlルーターの他のリソースは
agent-sandbox-systemNamespace にあります。これは次のステップで削除されます。Agent Sandbox コントローラ、その Namespace、CustomResourceDefinition を削除するには、インストールしたバージョンのリリース マニフェストを削除します。
kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml
リソースのクリーンアップ
Google Cloud アカウントに課金されないようにするには、作成した GKE クラスタを削除します。
gcloud container clusters delete ${CLUSTER_NAME} \
--location=${LOCATION} \
--quiet
Autopilot クラスタを作成した場合、ロケーションはリージョン（us-central1 など）です。Standard クラスタを作成した場合、ロケーションはゾーン（us-central1-a など）です。
次のステップ
- Pod スナップショットを使用して GKE 環境で Agent Sandbox を保存して復元する方法を学習する。
- GKE の Agent Sandbox で使用される基盤となるテクノロジーについて学習する。
- GKE セキュリティの詳細を確認する。
- GitHub で Agent Sandbox オープンソース プロジェクトを確認する。
- GKE で Agent Sandbox と Kata Containers（オープンソース）を使用する方法を学習する。Kata Containers は Google Cloud プロダクトではありません。このソフトウェアをインストールして使用する場合は、管理とトラブルシューティングを行う必要があります。Google のサポートと SLA は Kata Containers には適用されません。