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

このドキュメントでは、Google Kubernetes Engine(GKE)クラスタの分離されたサンドボックスで AI 生成コードを実行する方法について説明します。クラスタにサンドボックス テンプレートと、準備完了のサンドボックスのプールを作成します。次に、プールからサンドボックスをリクエストし、サンドボックスでコマンドを実行する Python スクリプトを実行します。このスクリプトは、サンドボックスの作成と管理を行うライブラリである Agent Sandbox Python クライアントを使用します。

信頼できないコードをサンドボックスで実行すると、AI 生成コードの潜在的な脆弱性からシステムを保護し、開発速度を向上させ、デプロイのセキュリティを強化できます。GKE の Agent Sandbox が信頼できない AI 生成コードを分離する方法の概要については、GKE の Agent Sandbox についてをご覧ください。

費用

GKE の Agent Sandbox は、追加料金なしで使用できるオープンソース ソフトウェアです。作成したリソース(Agent Sandbox コントローラが使用するコンピューティング リソースなど)には、GKE の料金が適用されます。

始める前に

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

    プロジェクトの選択または作成に必要なロール

    • プロジェクトを選択する: プロジェクトを選択する際に、特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトを選択できます。
    • プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者のロール(roles/resourcemanager.projectCreator)が必要です。詳しくは、ロールを付与する方法をご覧ください。

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

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

  3. 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 コントローラがインストールされ、Sandbox Router がデプロイされている GKE クラスタがあることを確認します。インストールしていない場合は、GKE に Agent Sandbox をインストールするの次のセクションのみを完了してから、このドキュメントに戻ります。
    1. 環境変数を定義する
    2. GKE クラスタを作成する
    3. Agent Sandbox をインストールする
    4. サンドボックス ルーターをデプロイする
    サンドボックス環境をデプロイするなど、そのドキュメントの他のセクションを完了する必要はありません。 このドキュメントの後半では、独自の SandboxTemplate リソースと SandboxWarmPool リソースを作成します。

必要なロール

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

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

環境変数を定義する

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

export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"

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

  • CLUSTER_NAME: GKE クラスタの名前(例: agent-sandbox-cluster)。
  • LOCATION: GKE クラスタが配置されている Google Cloud リージョンまたはゾーン。Autopilot クラスタを使用する場合は、リージョン(us-central1 など)に設定します。Standard クラスタを使用する場合は、ゾーン(us-central1-a など)に設定します。

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

このセクションでは、サンドボックス ブループリント(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/v1beta1
    kind: SandboxTemplate
    metadata:
      name: python-sandbox-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/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: python-sandbox-warmpool
      namespace: default
    spec:
      replicas: 2
      sandboxTemplateRef:
        name: python-sandbox-template
    
  2. SandboxTemplate マニフェストと SandboxWarmPool マニフェストを適用します。

    kubectl apply -f sandbox-template-and-pool.yaml
    
  3. ウォームプールのサンドボックスの準備が整うまで待ちます。

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
        --for=jsonpath='{.status.readyReplicas}'=2 \
        --timeout=600s
    

    このドキュメントの後半では、Python クライアントが SandboxClaim リソースを作成します。プールのサンドボックスが準備される前にクライアントがクレームを作成すると、コントローラはプールからサンドボックスを割り当てるのではなく、クレーム用に新しいサンドボックスを作成することがあります。Autopilot クラスタでは、GKE がノードを作成する必要があるため、サンドボックスの準備が完了するまでに数分かかることがあります。

Sandbox Router を確認する

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

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

Sandbox Router が agent-sandbox-system Namespace で実行されていることを確認します。

kubectl get deployment sandbox-router --namespace=agent-sandbox-system

ルーターが実行されている場合、READY 列には、すべてのレプリカが準備完了であることを示す値(2/2 など)が表示されます。コマンドが NotFound エラーを返した場合は、サンドボックス ルーターをデプロイするの手順に沿ってルーターをデプロイします。

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

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

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

    python3 -m venv .venv
    source .venv/bin/activate
    
  2. クライアント パッケージをインストールします。Agent Sandbox コントローラと同じバージョンを使用します。

    pip install k8s-agent-sandbox==1.0.6
    

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

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

  1. 次の内容の Python スクリプトを test_sandbox.py という名前で作成します。

    from k8s_agent_sandbox import SandboxClient
    from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig
    
    # Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace.
    # cleanup=True deletes the sandbox when the script exits.
    client = SandboxClient(
        connection_config=SandboxLocalTunnelConnectionConfig(),
        cleanup=True,
    )
    
    sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", 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.commands.run() メソッドを使用すると、任意のシェルコマンドを実行できます。GKE の Agent Sandbox は、クラスタのノードや他のワークロードを信頼できないコードから保護する安全なバリア内でコマンドを実行します。これにより、AI エージェントや自動化されたワークフローがタスクを実行するための安全で信頼性の高い方法が提供されます。

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

SandboxClaim リソースが作成されると、ウォームプールから利用可能なサンドボックスがクレームに割り当てられ、クレームは準備完了としてマークされます。その後、SandboxWarmPool リソースは自動的に補充され、構成された数のレプリカが維持されます。

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

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

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

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

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

    • コントローラ アプリケーションが同じクラスタ内の Pod として実行されている場合は、Kubernetes RBAC または Workload Identity Federation for GKE と IAM ポリシーを使用して、Pod の Kubernetes ServiceAccount にサンドボックスの監視やネットワーク エンドポイントの検出に必要な権限を付与します。
    • コントローラ アプリケーションがクラスタの外部で実行されている場合は、Workload Identity 連携または IAM サービス アカウントを使用して、許可ポリシーで参照できる ID をアプリケーションに付与します。
  • ルーティング: コントローラ アプリケーションの Python クライアントからのリクエストが、クラスタ内のサンドボックス ルーターに到達する必要があります。本番環境では、次のいずれかの方法でネットワーク接続を確立します。

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

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

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

  • ネットワーク ポリシーの制限: デフォルトでは、GKE の Agent Sandbox は厳格なセキュア バイ デフォルトのネットワーク ポスチャー(networkPolicyManagement: Managed)を適用します。このポスチャーでは、次の制限が適用されます。

    • 指定されたサンドボックス ルーター(agent-sandbox-system Namespace で app: sandbox-router ラベルが付いている Pod)を除くすべてのソースからの上り(内向き)がブロックされます。
    • 下り(外向き)は、公共のインターネットに対して許可されますが、プライベート LAN 範囲(RFC 1918)、内部クラスタ DNS(CoreDNS)、クラウド プロバイダ メタデータ サーバー(169.254.0.0/16)への下り(外向き)は明示的にブロックされます。

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

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

デフォルトでは、GKE の Agent Sandbox はサンドボックスにセキュリティ ポリシーを適用しません。サンドボックスの分離設定を適用するには、Agent Sandbox GitHub リポジトリから推奨される secure-sandbox-policy Kubernetes Validating Admission Policy(VAP)を適用します。手順については、推奨されるセキュリティ ポリシーを適用するをご覧ください。

このポリシーは、gVisor の要求、hostNetwork の無効化、hostPath ボリュームのブロックなど、分離要件を適用します。このポリシーでは、すべての機能の削除、新しい機能の追加の防止、コンテナを非 root として実行すること、リソース上限の設定など、強化要件も適用されます。要件の完全なリストについては、GKE での Agent Sandbox のデプロイ要件をご覧ください。

ポリシーの制約を変更または削除する

ポリシーは自分で適用するため、ワークロードに合わせて変更できます。ワークロードで一部のルールを免除する必要がある場合は、ポリシーを変更して特定の制約を削除するか、ポリシー バインディングを完全に削除します。制約を削除すると、ポリシーによって提供される分離が減少するため、ワークロードに必要な制約のみを削除してください。

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

kubectl edit validatingadmissionpolicy secure-sandbox-policy

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

また、クラスタでポリシーの適用を停止する場合は、ポリシー バインディングを削除します。

kubectl delete validatingadmissionpolicybinding secure-sandbox-binding

既知の問題

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

サービス メッシュの使用時にセキュリティ ポリシーが機能をブロックする

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

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'secure-sandbox-policy' with binding 'secure-sandbox-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 などの機能が必要です。secure-sandbox-policy ValidatingAdmissionPolicy は、すべてのコンテナタイプですべての機能の追加をブロックします。
  • 回避策: このポリシーはクラスタで管理するため、ValidatingAdmissionPolicy を変更して、特定の信頼できる init コンテナが NET_ADMIN と NET_RAW の機能をリクエストできるようにします。ポリシー制約を変更または削除する方法については、ポリシー制約を変更または削除するをご覧ください。たとえば、ポリシーの検証式または変数を更新して、信頼できるコンテナ名を機能ルールから除外できます。

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 トラフィックがクラスタに戻るようにするには、VPC ネットワークで有効な IPv6 Cloud NAT またはインターネット ゲートウェイを構成します。
    • ワークロードで 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

次のステップ