Agent Sandbox で AI コードの実行を分離する

Autopilot Standard

デベロッパー環境をデプロイして、Google Kubernetes Engine（GKE）クラスタで Agent Sandbox Python クライアントを使用できます。この設定により、サンドボックス化された Python 環境内で信頼できないコードを分離することで、AI 生成コードを安全に実行してテストできます。この分離は、AI 生成コードの潜在的な脆弱性からシステムを保護し、開発速度を向上させ、安全なデプロイを確保するために不可欠です。Agent Sandbox 機能が信頼できない AI 生成コードを分離する方法の概要については、GKE Agent Sandbox についてをご覧ください。

費用

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

始める前に

1. コンソールの Google Cloud プロジェクト セレクタページで、 Google Cloud プロジェクトを選択または作成します。

   プロジェクトを選択または作成するために必要なロール

   • プロジェクトを選択する: プロジェクトの選択には特定の IAM ロールは必要ありません。ロールが付与されている任意のプロジェクトを選択できます。
   • プロジェクトを作成する: プロジェクトを作成するには、プロジェクト作成者ロール （roles/resourcemanager.projectCreator）が必要です。これには resourcemanager.projects.create 権限が含まれています。詳しくは、ロールを付与する方法をご覧ください。
   注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、 プロジェクトに関連するすべてのリソースを削除できます。

   プロジェクト セレクタに移動

2. プロジェクトで課金が有効になっていることを確認します Google Cloud 。

3. Artifact Registry API と Kubernetes Engine API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。詳しくは、ロールを付与する方法をご覧ください。

   API を有効にする

4. コンソール Google Cloud で Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

5. このドキュメントを完了するために必要な権限があることを確認します
6. Agent Sandbox 機能が有効になっている GKE クラスタが必要です。ない場合は、GKE で Agent Sandbox を有効にするの手順に沿って、新しいクラスタを作成するか、既存のクラスタを更新します。

必要なロール

サンドボックスの作成と管理に必要な権限を取得するには、プロジェクトに対するKubernetes Engine 管理者 （roles/container.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

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

環境変数を定義する

このドキュメントで実行するコマンドを簡略化するために、Cloud Shell で環境変数を設定できます。Cloud Shell で、次のコマンドを実行して環境変数を定義します。

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

これらの環境変数の説明は次のとおりです。

• PROJECT_ID: 現在の Google Cloud プロジェクトの ID。この変数を定義すると、GKE クラスタなどのすべてのリソースが正しいプロジェクトに作成されます。
• CLUSTER_NAME: GKE クラスタの名前（例: agent-sandbox-cluster）。
• LOCATION: GKE クラスタが配置されている Google Cloud リージョンまたはゾーン。Autopilot クラスタを使用している場合はリージョン（us-central1 など）、Standard クラスタを使用している場合はゾーン（us-central1-a など）に設定します。
• NODE_POOL_NAME: サンドボックス化されたワークロードを実行するノードプールの名前（例: agent-sandbox-node-pool）。
• MACHINE_TYPE: ノードプール内のノードのマシンタイプ（e2-standard-2 など）。さまざまなマシンシリーズと さまざまなオプションの選択の詳細については、 マシン ファミリーのリソースと比較ガイドをご覧ください。

サンドボックス環境をデプロイする

このセクションでは、サンドボックス ブループリント（SandboxTemplate）を作成し、必要なネットワーキング ルーターをデプロイして、サンドボックスの操作に使用する Python クライアントをインストールする方法について説明します。

サンドボックスを作成して操作するには、Agentic Sandbox Python クライアントを使用することをおすすめします。このクライアントは、サンドボックスの作成からクリーンアップまでのライフサイクル全体を簡素化するインターフェースを提供します。これは、サンドボックスの作成、使用、削除をプログラムで行うために使用できる Python ライブラリです。

クライアントは、すべてのトラフィックの中央エントリ ポイントとしてサンドボックス ルーターを使用します。このドキュメントで説明する例では、クライアントは kubectl port-forward コマンドを使用してこのルーターへのトンネルを作成するため、パブリック IP アドレスを公開する必要はありません。 kubectl port-forward の使用は安全なソリューションではなく、 開発環境での使用に限定する必要があります。

SandboxTemplate と SandboxWarmPool を作成する

SandboxTemplate リソースと SandboxWarmPool リソースを作成して、サンドボックスの構成を定義します。SandboxTemplate は、Agent Sandbox コントローラが使用して、一貫性のある事前構成済みのサンドボックス環境を作成する再利用可能なブループリントとして機能します。SandboxWarmPool リソースは、指定された数の事前にウォームアップされた Pod が常に実行され、要求される準備ができていることを保証します。 事前にウォームアップされたサンドボックスは、すでに初期化されている実行中の Pod です。この事前初期化により、新しいサンドボックスを 1 秒以内に作成できるようになり、通常のサンドボックスの起動時のレイテンシを回避できます。

1. Cloud Shell で、次の内容を含むファイルを sandbox-template-and-pool.yaml という名前で作成します。

   apiVersion: extensions.agents.x-k8s.io/v1alpha1
   kind: SandboxTemplate
   metadata:
     name: python-runtime-template
     namespace: default
   spec:
     podTemplate:
       metadata:
         labels:
           sandbox: python-sandbox-example
       spec:
         runtimeClassName: gvisor
         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: python-runtime
           image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
           ports:
           - containerPort: 8888
           readinessProbe:
             httpGet:
               path: "/"
               port: 8888
             initialDelaySeconds: 0
             periodSeconds: 1
           resources:
             requests:
               cpu: "250m"
               memory: "512Mi"
             limits:
               cpu: "500m"
               memory: "1Gi" # Required
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
         restartPolicy: "OnFailure"
   ---
   apiVersion: extensions.agents.x-k8s.io/v1alpha1
   kind: SandboxWarmPool
   metadata:
     name: python-sandbox-warmpool
     namespace: default
   spec:
     replicas: 2
     sandboxTemplateRef:
       name: python-runtime-template
   

2. SandboxTemplate マニフェストと SandboxWarmPool マニフェストを適用します。

   kubectl apply -f sandbox-template-and-pool.yaml
   

サンドボックス ルーターをデプロイする

サンドボックス環境の作成と操作に使用する Python クライアントは、サンドボックス ルーターと呼ばれるコンポーネントを使用してサンドボックスと通信します。

この例では、テストにクライアントのデベロッパー モードを使用します。このモードはローカル開発を目的としており、kubectl port-forward コマンドを使用して、ローカルマシンから、クラスタで実行されているサンドボックス ルーター サービスへの直接トンネルを確立します。このトンネリング アプローチでは、パブリック IP アドレスや複雑な上り（内向き）設定が不要になり、ローカル環境からのサンドボックスの操作が簡素化されます。

サンドボックス ルーターをデプロイする手順は次のとおりです。

1. Cloud Shell で、次の内容を含むファイルを sandbox-router.yaml という名前で作成します。

   # A ClusterIP Service to provide a stable endpoint for the router pods.
   apiVersion: v1
   kind: Service
   metadata:
     name: sandbox-router-svc
     namespace: default
   spec:
     type: ClusterIP
     selector:
       app: sandbox-router
     ports:
     - name: http
       protocol: TCP
       port: 8080 # The port the service will listen on
       targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
   ---
   # The Deployment to manage and run the router pods.
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: sandbox-router-deployment
     namespace: default
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: sandbox-router
     template:
       metadata:
         labels:
           app: sandbox-router
       spec:
         # Ensure pods are spread across different zones for HA
         topologySpreadConstraints:
           - maxSkew: 1
             topologyKey: topology.kubernetes.io/zone
             whenUnsatisfiable: ScheduleAnyway
             labelSelector:
               matchLabels:
                 app: sandbox-router
         containers:
         - name: router
           image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:latest-main
           ports:
           - containerPort: 8080
           readinessProbe:
             httpGet:
               path: /healthz
               port: 8080
             initialDelaySeconds: 5
             periodSeconds: 5
           livenessProbe:
             httpGet:
               path: /healthz
               port: 8080
             initialDelaySeconds: 10
             periodSeconds: 10
           resources:
             requests:
               cpu: "100m"
               memory: "512Mi"
             limits:
               cpu: "1000m"
               memory: "1Gi"
         securityContext:
           runAsUser: 1000
           runAsGroup: 1000
   

   ベスト プラクティス:

   この例では、常に最新のビルドを指す 最新のビルドを指す `latest-main` イメージタグを使用します。本番環境での安定性を確保するには、そのバージョンの SHA-256 イメージ ダイジェストを使用して特定のイメージ バージョンをプルします。たとえば、 `sandbox-router@sha256:b158ea22b405af60fe4d00abfca12caea5465fd30b5f30a4b6184c8115925f51`。 イメージ名にイメージ ダイジェストを指定すると、実行するコードが固定されるため、リポジトリの変更によってクラスタ内のイメージが更新されることはありません。

2. マニフェストを適用して、ルーターをクラスタにデプロイします。

   kubectl apply -f sandbox-router.yaml
   

3. サンドボックス ルーターのデプロイが正しく実行されていることを確認します。

   kubectl get deployment sandbox-router-deployment
   

   デプロイの READY 列に 2/2 または 1/1 が表示されるまで待ちます。

Python クライアントをインストールする

サンドボックス ルーターなどのクラスタ内コンポーネントがデプロイされたので、最後の準備手順として、ローカルマシンに Agentic Sandbox Python クライアントをインストールします。このクライアントは、サンドボックスをプログラムで作成、使用、削除できる Python ライブラリです。次のセクションで、環境のテストに使用します。

1. Python 仮想環境を作成してアクティブにします。

   python3 -m venv .venv
   source .venv/bin/activate
   

2. クライアント パッケージをインストールします。

   pip install k8s-agent-sandbox
   

サンドボックスをテストする

すべての設定コンポーネントが整ったので、Agentic Sandbox Python クライアントを使用してサンドボックスを作成し、操作できるようになりました。

1. agent-sandbox ディレクトリに、次の内容の Python スクリプトを test_sandbox.py という名前で作成します。

   from k8s_agent_sandbox import SandboxClient
   from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig
   
   # Automatically tunnels to svc/sandbox-router-svc
   client = SandboxClient(
       connection_config=SandboxLocalTunnelConnectionConfig()
   )
   
   sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
   try:
       print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
   except Exception as e:
       print(f"An error occurred: {e}")
   

2. ターミナルから（仮想環境がアクティブな状態で）、テスト スクリプトを実行します。

   python3 test_sandbox.py
   

サンドボックスから出力される「Hello from the sandboxed environment!」というメッセージが表示されます。

これで完了です。安全なサンドボックス内でシェルコマンドが正常に実行されました。sandbox.run() メソッドを使用すると、任意のシェルコマンドを実行できます。Agent Sandbox は、クラスタのノードや他のワークロードを信頼できないコードから保護する安全なバリア内でコマンドを実行します。これにより、AI エージェントや自動化されたワークフローがタスクを実行するための安全で信頼性の高い方法が提供されます。

スクリプトの実行時に、SandboxClient によってすべての手順が処理されます。SandboxClaim リソースを作成してサンドボックスを起動し、サンドボックスの準備が整うまで待機してから、sandbox.run() メソッドを使用して安全なコンテナ内で bash シェルコマンドを実行します。クライアントは、そのコマンドから stdout をキャプチャして出力します。サンドボックスは、プログラムの実行後に自動的に削除されます。

SandboxClaim リソースが作成されると、使用可能な Pod がウォームプールから Sandbox オブジェクトに割り当てられ、クレームが準備完了とマークされます。その後、SandboxWarmPool は自動的に補充され、構成されたレプリカ数が維持されます。

特定のサンドボックスが要求されているか使用可能かを確認するには、サンドボックス Pod のメタデータの ownerReferences を確認します。kind フィールドの値が Sandbox の場合、Pod は使用中です。kind フィールドの値が SandboxWarmPool の場合、Pod はアイドル状態で、要求されるのを待っています。

本番環境でサンドボックスを実行する

このドキュメントでは、Cloud Shell を使用してクラスタの外部からサンドボックスを操作します。Python クライアントは、ユーザー認証情報を使用してクラスタを認証し、サンドボックス リソースを管理します。また、kubectl port-forward コマンドを使用してサンドボックスとの接続を確立します。これらの手順は、開発シナリオに適しています。

本番環境のシナリオでは、コントローラ アプリケーション（AI オーケストレーターなど）がサンドボックス リソースの作成と管理を行います。本番環境で Agent Sandbox を使用する場合は、次の点を考慮してください。

• 認証: コントローラ アプリケーションは、サンドボックスを実行するために クラスタ API サーバーに対して認証を行う必要があります。認証の構成方法は、コントローラ アプリケーションの実行場所によって異なります。

  • コントローラ アプリケーションが同じクラスタ内の Pod として実行される場合は、 Kubernetes RBAC またはWorkload Identity Federation for GKE と IAM ポリシーを使用して、Pod の Kubernetes ServiceAccount に、サンドボックスの監視または ネットワーク エンドポイントの検出に必要な権限を付与します。
  • コントローラ アプリケーションがクラスタの外部で実行される場合は、 Workload Identity 連携 または IAM サービス アカウントを使用して、許可ポリシーで参照できる ID をアプリケーションに付与します。

• ルーティング: コントローラ アプリケーションの Python クライアントからのリクエストは クラスタ内のサンドボックス ルーターに到達する必要があります。本番環境では、次のいずれかの方法でネットワーク接続を確立します。

  • コントローラ アプリケーションが同じクラスタで実行されている場合は、SandboxDirectConnectionConfig 関数を使用して、サンドボックス ルーター サービスが使用する URL とポートをターゲットにします。
  • コントローラ アプリケーションがクラスタの外部で実行される場合は、 the GKE Gateway API を使用して内部ロードバランサまたは外部ロードバランサを作成します。クライアント コードで、SandboxGatewayConnectionConfig 関数を使用して Gateway を参照します。

  これらのルーティング方法の詳細については、 GitHub の使用例 と ルーターの Gateway デプロイ手順をご覧ください。

• リソースへの Google Cloud サンドボックス アクセス: サンドボックス コードで Cloud Storage などの Google Cloud API にリクエストを送信する必要がある場合は、 Workload Identity Federation for GKE で IAM ポリシーを使用して、サンドボックス Pod が使用する Kubernetes ServiceAccount に、 そのアクセスに必要な権 101 限を付与します。デフォルトのネットワーク ポリシーでは Google Cloud メタデータ サーバー （169.254.169.254）へのアクセスがブロックされるため、この トラフィックを許可するようにネットワーク ポリシーをカスタマイズする必要があります。

• ネットワーク ポリシーの制限 : デフォルトでは、Agent Sandbox は 厳格なデフォルトで安全なネットワーク ポスチャー（networkPolicyManagement: Managed）を適用します。このポスチャーでは、次の制限が適用されます。

  • 指定されたサンドボックス ルーターを除くすべてのソースからの上り（内向き） はブロックされます。
  • 下り（外向き） はパブリック インターネットに許可されますが、プライベート LAN 範囲（RFC 1918）、内部クラスタ DNS（CoreDNS）、Cloud Provider メタデータ サーバー（169.254.0.0/16）への下り（外向き）は明示的にブロックされます。

  Workload Identity Federation for GKE を使用する場合や、他のプライベート リソースにアクセスする場合は、SandboxTemplate でカスタム ネットワーク ポリシーを定義する必要があります。詳細な 構成の詳細とカスタマイズ可能なテンプレート（ エアギャップ サンドボックスや Workload Identity Federation for GKE の統合など）については、Agent Sandbox ネットワーク ポリシーの管理をご覧ください。

サンドボックス セキュリティ ポリシー

デフォルトで安全な環境を確保するため、GKE Agent Sandbox アドオンは Kubernetes 検証アドミッションポリシー（VAP）を使用して、Sandbox リソースと SandboxTemplate リソースに セキュリティ制約を適用します。これらのポリシーは自動的に適用されます。

注: ポリシーの分割は、クラスタ バージョン 1.36.0-gke.2459000 以降でサポートされています。 既存のクラスタの VAP を更新するには、ポリシーを変更する手順を行う前に、クラスタ バージョンを 1.36.0-gke.2459000 以降にアップグレードします。

このアドオンは、柔軟性を高めるために、セキュリティ適用を 2 階層のポリシーモデルに分割します。以降のセクションでは、厳密に管理されたコアポリシーとカスタマイズ可能な強化ポリシーについて説明します。

コア セキュリティ ポリシー（sandbox-core-policy）

コア セキュリティ ポリシーは、サンドボックスの整合性を保護するのに役立つ分離要件を適用します。このポリシーには、gVisor の使用、hostNetwork の無効化などのネットワーク分離、hostPath のブロックなどのファイル システム分離を必要とするルールが含まれています。GKE は addonmanager.kubernetes.io/mode: Reconcile 設定でこのポリシーを管理するため、これらのコアルールを変更またはオーバーライドすることはできません。

セキュリティ強化ポリシー（sandbox-hardening-policy）

セキュリティ強化ポリシーは、セキュリティに関する追加のベスト プラクティスと管理オプションを提供します。すべての機能の削除、新しい機能の追加の防止、リソース制限付きの非 root としてのコンテナの実行などの制約を適用します。GKE は、addonmanager.kubernetes.io/mode: EnsureExists 設定を使用して、EnsureExists モードでこのポリシーをデプロイします。この設定は、ポリシーが存在しない場合に GKE がポリシーを作成することを意味しますが、必要に応じてポリシーまたはそのバインディングを変更または削除できます。

強化制約を変更または削除する

強化ポリシーは EnsureExists モードでデプロイされるため、ポリシーが存在しない場合は GKE がポリシーを作成しますが、変更は上書きされません。ワークロードでこれらの強化ルールからの除外が必要な場合は、ポリシーを変更して特定の制約を削除するか、ポリシー バインディングを完全に削除できます。

強化ポリシーを変更して特定の制約を削除する（たとえば、コンテナを root として実行できるようにする、またはリソース制限を省略する）には、ValidatingAdmissionPolicy リソースを編集します。

kubectl edit validatingadmissionpolicy sandbox-hardening-policy

開いたテキスト エディタで、validations セクションを見つけて、ワークロードをブロックする制約式を削除または変更します。

または、クラスタの強化ポリシーを完全に無効にする場合は、ポリシー バインディングを削除します。

kubectl delete validatingadmissionpolicybinding sandbox-hardening-binding

既知の問題

このセクションでは、GKE で Agent Sandbox を使用する際の既知の問題と、その解決方法または回避策について説明します。

サービス メッシュを使用すると、セキュリティ ポリシーによって機能がブロックされる

サービス メッシュ サイドカー（Envoy や Istio など）と統合するサンドボックスをデプロイしようとすると、次のエラーで強化セキュリティ ポリシーによってサンドボックスの作成がブロックされることがあります。

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'sandbox-hardening-policy' with binding 'sandbox-hardening-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.

• 原因: サービス メッシュ サイドカーは、 istio-init や proxy-init などの init コンテナを使用することがよくあります。これらの init コンテナでは、透過的な下り（外向き）ルーティングの iptables ルールを構成するために、NET_ADMIN や NET_RAW などの機能が必要です。 デフォルトでは、GKE sandbox-hardening-policy は、すべてのコンテナタイプで機能の追加をブロックします。
• 回避策: GKE 強化ポリシーは `EnsureExists` モードでデ 2/}プロイされるため、ValidatingAdmissionPolicy`ValidatingAdmissionPolicy` を 変更して、特定の信頼できる init コンテナがNET_ADMIN`NET_ADMIN` 機能とNET_RAW`NET_RAW` 機能 をリクエストできるようにします。EnsureExistsこれらの 強化制約を変更または削除する方法については、 強化制約を変更または削除するをご覧ください。 たとえば、ポリシーの検証式または変数を更新して、信頼できるコンテナ名を機能ルールから除外できます。

IPv6 経由で Google API に接続する際の下り（外向き）レイテンシまたはタイムアウト

サンドボックス内のワークロードで、外部リソースまたは Google API（Vertex AI や Cloud Storage など）に接続しようとすると、接続タイムアウトや 2 分もの長いレイテンシが発生することがあります。

• 原因: GKE クラスタでデュアルスタック IPv6 が有効になっている場合、 Google API の DNS の解決では IPv4（A）アドレスと IPv6（AAAA） アドレスの両方が返されます。Node.js などのランタイム エンジンのアルゴリズムによっては、最初に IPv6 経由で接続しようとします。GKE VPC に有効な IPv6 下り（外向き）ルート（Cloud NAT や IPv6 のインターネット ゲートウェイなど）がない場合、TCP SYN タイムアウトが期限切れになるまで TCP 接続は応答を停止します。その後、TCP 接続は IPv4 にフォールバックします。

• 解決策: この問題を解決するには、次のいずれかを行います。

  • IPv6 下り（外向き）を構成する: 送信 IPv6 トラフィック がクラスタに戻るようにするには、有効な IPv6 Cloud NAT または インターネット ゲートウェイを VPC ネットワークで構成します。

  • ワークロードで IPv4 を優先する: IPv4 の DNS の解決を優先するには、 ワークロードのランタイムを構成します。たとえば、Node.js アプリケーションでは、SandboxTemplate 定義で次の環境変数を設定できます。

    env:
    - name: NODE_OPTIONS
      value: "--dns-result-order=ipv4first --no-network-family-autoselection"
    

リソースのクリーンアップ

Google Cloud アカウントに課金されないようにするには、作成した GKE クラスタを削除する必要があります。

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

次のステップ

• Pod スナップショットを使用して Agent Sandbox 環境を保存して復元する方法を学習する。
• Agent Sandbox オープンソース プロジェクトの詳細については、GitHub をご覧ください。
• Agent Sandbox でオープンソースの Kata Containers を使用する方法を学習する。 Kata Containers は Google Cloud プロダクトではありません。このソフトウェアをインストールして使用する場合は、管理とトラブルシューティングを行う必要があります。 Google のサポートと SLA は Kata Containers には適用されません。
• ワークロードのセキュリティ分離を提供する基盤となるテクノロジーについては、GKE Sandboxをご覧ください。
• クラスタとワークロードのセキュリティ強化の詳細については、 GKE セキュリティの概要をご覧ください。