このドキュメントでは、Google Kubernetes Engine（GKE）クラスタでエージェント サンドボックス機能を有効にする方法について説明します。また、信頼できないコードを安全に実行するためのサンドボックス環境をクラスタに作成する方法についても説明します。
Agent Sandbox 機能が信頼できない AI 生成コードを分離する方法の概要については、GKE Agent Sandbox についてをご覧ください。
費用
Agent Sandbox は、GKE で追加料金なしで利用できます。作成したリソースには GKE の料金が適用されます。
不要な料金が発生しないように、このドキュメントの完了後に GKE を無効にするか、プロジェクトを削除してください。
始める前に
-
Google Cloud コンソールのプロジェクト セレクタページで、 Google Cloud プロジェクトを選択または作成します。
プロジェクトの選択または作成に必要なロール
- プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
-
プロジェクトを作成する: プロジェクトを作成するには、
resourcemanager.projects.create権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。
Artifact Registry API と Google Kubernetes Engine API を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。-
Google Cloud コンソールで Cloud Shell をアクティブにします。
- クラスタで GKE バージョン 1.35.2-gke.1269000 以降が実行されていることを確認します。
環境変数を定義する
このドキュメントで実行するコマンドを簡略化するために、Cloud Shell で環境変数を設定できます。Cloud Shell で、次のコマンドを実行して環境変数を定義します。
export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.35.2-gke.1269000"
export NODE_POOL_NAME="agent-sandbox-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など）に設定します。CLUSTER_VERSION: クラスタが実行する GKE のバージョン。エージェント サンドボックス機能には、バージョン 1.35.2-gke.1269000 以降が必要です。NODE_POOL_NAME: サンドボックス化されたワークロードを実行するノードプールの名前（例:agent-sandbox-pool）。この変数は、GKE Standard クラスタを作成する場合にのみ必要です。MACHINE_TYPE: ノードプール内のノードのマシンタイプ（e2-standard-2など）。さまざまなマシンシリーズとさまざまなオプションの選択の詳細については、マシン ファミリーのリソースと比較ガイドをご覧ください。この変数は、GKE Standard クラスタを作成する場合にのみ必要です。
Agent Sandbox を有効にする
エージェント サンドボックス機能は、新しいクラスタを作成するとき、または既存のクラスタを更新するときに有効にできます。
新しい GKE クラスタを作成するときにエージェント サンドボックスを有効にする
フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用することをおすすめします。ワークロードに最適な GKE の運用モードを選択するには、GKE の運用モードを選択するをご覧ください。
Autopilot
エージェント サンドボックスを有効にして新しい GKE Autopilot クラスタを作成するには、--enable-agent-sandbox フラグを含めます。
gcloud beta container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION} \
--cluster-version=${CLUSTER_VERSION} \
--enable-agent-sandbox
Autopilot クラスタの場合は、LOCATION 環境変数がリージョン（us-central1 など）に設定されていることを確認します。
標準
エージェント Sandbox を有効にして新しい GKE Standard クラスタを作成するには、クラスタを作成し、gVisor を有効にしてノードプールを追加してから、エージェント Sandbox 機能を有効にする必要があります。費用を抑えるには、プールごとに 1 つのノードを持つゾーンクラスタを作成することをおすすめします。
クラスタを作成します。
gcloud beta container clusters create ${CLUSTER_NAME} \ --location=${LOCATION} \ --num-nodes=1 \ --cluster-version=${CLUSTER_VERSION}この Standard クラスタでは、
LOCATION環境変数がゾーン（us-central1-aなど）に設定されていることを確認します。gVisor を有効にして、独立したノードプールを作成します。
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=gvisorLOCATIONは、クラスタの作成時に使用したゾーンと同じである必要があります。クラスタを更新して Agent Sandbox 機能を有効にします。
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
既存の GKE クラスタを更新するときに Agent Sandbox を有効にする
既存のクラスタでエージェント サンドボックスを有効にするには、クラスタでバージョン 1.35.2-gke.1269000 以降を実行している必要があります。
LOCATION 環境変数が、既存のクラスタが配置されているリージョンまたはゾーンに設定されていることを確認します。
GKE Standard クラスタを使用している場合、Agent Sandbox は gVisor に依存します。Standard クラスタに gVisor 対応のノードプールがない場合は、まずノードプールを作成する必要があります。
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --machine-type=${MACHINE_TYPE} \ --location=${LOCATION} \ --image-type=cos_containerd \ --sandbox=type=gvisorクラスタを更新して Agent Sandbox 機能を有効にします。
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
構成を確認する
Agent Sandbox 機能が有効になっているかどうかを確認するには、クラスタの説明を調べます。
gcloud beta container clusters describe ${CLUSTER_NAME} \
--location=${LOCATION} \
--format="value(addonsConfig.agentSandboxConfig.enabled)"
Autopilot クラスタを作成した場合は、ロケーションはリージョン（us-central1 など）です。Standard クラスタを作成した場合は、ロケーションはゾーン（us-central1-a など）です。
機能が正常に有効になると、コマンドは True を返します。
Agent Sandbox のデプロイ要件
Sandbox や SandboxTemplate などのワークロードを正常にデプロイするには、YAML マニフェストに特定のセキュリティ設定と構成設定を含める必要があります。GKE は、検証用アドミッション ポリシー（VAP）を使用してこれらの要件を適用します。これらの要件が満たされていない場合、アドミッション コントローラはデプロイを拒否します。
必要な構成
デプロイ マニフェストには、次の設定を含める必要があります。
runtimeClassName: gvisor: Pod が gVisor Sandbox で実行されるようにします。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。 HostPath巻。- 機能を追加しました（
capabilities.add）。 hostPortの設定。- カスタム sysctl。
- サービス アカウント トークンまたは証明書の予測ボリューム。
サンドボックス環境をデプロイする
SandboxTemplate を定義し、SandboxWarmPool を使用して事前ウォーミングされたインスタンスを準備しておくことで、サンドボックス環境をデプロイすることをおすすめします。SandboxClaim を使用して、このウォーム ノードプールからインスタンスをリクエストできます。または、サンドボックスを直接作成することもできますが、この方法ではウォームプールはサポートされません。
SandboxTemplate、SandboxWarmPool、SandboxClaim、Sandbox は Kubernetes カスタム リソースです。
推奨: SandboxTemplate と SandboxWarmPool を作成する
SandboxTemplate は、再利用可能なブループリントとして機能します。SandboxWarmPool は、指定された数の事前にウォームアップされた Pod が常に実行され、要求される準備ができていることを保証します。このお客様のリソースを使用すると、起動レイテンシを最小限に抑えることができます。
SandboxTemplate と SandboxWarmPool を作成してサンドボックス環境をデプロイする手順は次のとおりです。
Cloud Shell で、次の内容を含むファイルを
sandbox-template.yamlという名前で作成します。apiVersion: extensions.agents.x-k8s.io/v1alpha1 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/v1alpha1 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
SandboxClaim を作成する
SandboxClaim は、テンプレートからサンドボックスをリクエストします。ウォームプールを作成したため、作成されたサンドボックスは新しい Pod を起動するのではなく、プールから実行中の Pod を採用します。
SandboxClaim を作成してテンプレートからサンドボックスをリクエストするには、次の操作を行います。
次の内容で
sandbox-claim.yamlという名前のファイルを作成します。apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxClaim metadata: name: sandbox-claim namespace: default spec: sandboxTemplateRef: # This must match the name of the SandboxTemplate. name: python-runtime-templateSandboxClaimマニフェストを適用します。kubectl apply -f sandbox-claim.yamlサンドボックス、クレーム、ウォームプールが準備できていることを確認します。
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
代替方法: Sandbox を直接作成する
ウォームプールで提供される高速な起動時間が必要ない場合は、テンプレートを使用せずにサンドボックスを直接デプロイできます。
Sandbox を直接作成してサンドボックス環境をデプロイする手順は次のとおりです。
次の内容で
sandbox.yamlという名前のファイルを作成します。apiVersion: agents.x-k8s.io/v1alpha1 kind: Sandbox metadata: name: sandbox-example-2 spec: replicas: 1 podTemplate: metadata: labels: sandbox: sandbox-example spec: runtimeClassName: gvisor restartPolicy: Always automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 # Required if image defaults to root (e.g. 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 を無効にする
エージェント サンドボックス機能を無効にするには、--no-enable-agent-sandbox フラグを指定して gcloud beta container clusters update コマンドを使用します。
gcloud beta container clusters update ${CLUSTER_NAME} \
--location=${LOCATION} \
--no-enable-agent-sandbox
Autopilot クラスタを作成した場合は、ロケーションはリージョン（us-central1 など）です。Standard クラスタを作成した場合は、ロケーションはゾーン（us-central1-a など）です。
リソースのクリーンアップ
Google Cloud アカウントに課金されないようにするには、作成した GKE クラスタを削除します。
gcloud container clusters delete $CLUSTER_NAME \
--location=${LOCATION} \
--quiet
Autopilot クラスタを作成した場合は、ロケーションはリージョン（us-central1 など）です。Standard クラスタを作成した場合は、ロケーションはゾーン（us-central1-a など）です。
次のステップ
- Pod スナップショットを使用して Agent Sandbox 環境を保存して復元する方法を学習する。
- Agent Sandbox で使用される基盤となるテクノロジーについて学習する。
- GKE セキュリティの詳細を確認する。
- GitHub で Agent Sandbox オープンソース プロジェクトを確認する。