Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

GKE Agent Sandbox の動的ストレージの遅延バインディングで Filestore エージェントボリュームを使用する

動的ストレージの遅延バインディングを使用すると、要求時に実行中の事前ウォームアップされた Google Kubernetes Engine（GKE）Agent Sandbox Pod に Filestore エージェントボリュームを直接挿入できます。標準の Kubernetes ボリュームアタッチメントライフサイクルをバイパスすることで、動的遅延バインディングは Pod の再起動を必要とせずに 100 ミリ秒未満のストレージアタッチメントレイテンシを実現します。

このアーキテクチャにより、高密度で低レイテンシのエージェントプラットフォームは次のことが可能になります。

Pod のコールドスタートとコンテナの初期化の遅延を解消します。
永続ワークスペースをオンデマンドで動的にアタッチおよびデタッチします。
アイドル状態のエージェントセッションを一時停止または休止し、ファイルシステムの状態を維持しながら、使用可能な事前ウォーミングされたサンドボックス Pod で再開します。

始める前に

Filestore エージェントボリュームの GKE 環境を設定するで初期設定を完了します。
GKE クラスタがバージョン 1.36.0-gke.3302001 以降を実行していることを確認します。このバージョンでは、gVisor emptyDir マウント伝播に必要な force-shared アノテーションがサポートされています。
volume-pool-sc StorageClass が volumeBindingMode: Immediate と reclaimPolicy: Delete を指定していることを確認します。

アーキテクチャの概要

遅延バインディングアーキテクチャは、次の 4 つのコンポーネントで構成されています。

プラットフォームオーケストレーターまたはカスタムコントローラ: セッションのライフサイクルを管理するコントロールプレーンサービスまたは Kubernetes コントローラ。SandboxClaim イベントを監視し、テナントボリュームのメタデータを解決し、ストレージノードデーモン API を呼び出してストレージをバインドまたはバインド解除し、削除ファイナライザーを管理します。
ストレージノードデーモン: マウント API を公開する各 gVisor ノードで実行される特権 DaemonSet。
force-shared を使用した SandboxTemplate: ホストマウントを gVisor サンドボックスコンテナに動的に伝播できる gVisor サンドボックス Pod テンプレート。
SandboxWarmPool: 事前にウォームアップされた実行中のサンドボックス Pod のプール。クレーム時にマウントリクエストをすぐに受信できます。

ストレージノードデーモンをデプロイする

特権 DaemonSet を含む storage-node-daemon.yaml という名前のマニフェストを作成します。

クリックして storage-node-daemon.yaml マニフェストを表示

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: storage-node-daemon
  namespace: default
spec:
  selector:
    matchLabels:
      app: storage-node-daemon
  template:
    metadata:
      labels:
        app: storage-node-daemon
    spec:
      hostPID: true
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
        - key: "sandbox.gke.io/runtime"
          operator: "Equal"
          value: "gvisor"
          effect: "NoSchedule"
      initContainers:
        - name: install-nfs
          image: debian:stable-slim
          securityContext:
            privileged: true
          volumeMounts:
            - name: host-root
              mountPath: /host-root
              mountPropagation: Bidirectional
          command: ["/bin/sh", "-c"]
          args:
            - |
              nsenter -t 1 -m -u -i -n -- apt-get update && \
              nsenter -t 1 -m -u -i -n -- apt-get install -y nfs-common || true
      containers:
        - name: daemon
          image: python:3.11-slim
          securityContext:
            privileged: true
          volumeMounts:
            - name: host-root
              mountPath: /host-root
              mountPropagation: Bidirectional
          command: ["python3", "-u", "-c"]
          args:
            - |
              import os, json, subprocess, traceback
              from http.server import BaseHTTPRequestHandler, HTTPServer

              def safe_join(base, *parts):
                  base = os.path.abspath(base)
                  path = os.path.abspath(os.path.join(base, *parts))
                  if os.path.commonpath([base, path]) != base:
                      raise ValueError("Path escapes base directory")
                  return path

              class Handler(BaseHTTPRequestHandler):
                  def do_POST(self):
                      try:
                          length = int(self.headers.get('Content-Length', 0))
                          data = json.loads(self.rfile.read(length))
                          pod_uid = data['pod_uid']
                          action = data['action']
                          volume_name = data['volume_name']
                          sub_dir = data['sub_dir']

                          parent = safe_join("/host-root/var/lib/kubelet/pods",
                                             pod_uid, "volumes/kubernetes.io~empty-dir", volume_name)
                          target = safe_join(parent, sub_dir)
                          host_target = safe_join("/var/lib/kubelet/pods", pod_uid,
                                                  "volumes/kubernetes.io~empty-dir", volume_name, sub_dir)

                          if action == "bind_nfs":
                              source = f"{data['nfs_server']}:{data['nfs_path']}"
                              os.makedirs(target, exist_ok=True)
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "mount", "-t", "nfs", "-o", "nolock", source, host_target], check=True)
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "chown", "-R", "1000:1000", host_target], check=True)
                              with open(f"{parent}/.ready", "w") as f:
                                  f.write("ready")
                              msg = f"Bound {source} to {host_target}"
                          elif action == "unbind":
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "umount", "-l", host_target], check=True)
                              msg = f"Unbound {host_target}"

                          self.send_response(200)
                          self.end_headers()
                          self.wfile.write(msg.encode())
                      except Exception:
                          err = traceback.format_exc()
                          self.send_response(500)
                          self.end_headers()
                          self.wfile.write(err.encode())

              HTTPServer(('localhost', 9090), Handler).serve_forever()
      volumes:
        - name: host-root
          hostPath:
            path: /

次のようにマニフェストを適用します。

kubectl apply -f storage-node-daemon.yaml

`SandboxTemplate` と `SandboxWarmPool` をデプロイする

テンプレートとウォームプールを含むマニフェストを sandbox-latebind.yaml という名前で作成します。

クリックして sandbox-latebind.yaml マニフェストを表示

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: late-bind-template
  namespace: default
spec:
  networkPolicyManagement: Unmanaged
  podTemplate:
    metadata:
      annotations:
        dev.gvisor.empty-dir.workspace-volume.force-shared: "true"
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
        - key: "sandbox.gke.io/runtime"
          value: "gvisor"
          effect: "NoSchedule"
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
      containers:
        - name: agent
          image: busybox:latest
          securityContext:
            capabilities:
              drop: ["ALL"]
            allowPrivilegeEscalation: false
          volumeMounts:
            - name: workspace-volume
              mountPath: /workspace
              mountPropagation: HostToContainer
          env:
            - name: MOUNT_PATH
              value: "/workspace"
            - name: SUB_DIR
              value: "user_data"
          command: ["/bin/sh", "-c"]
          args:
            - |
              echo "Waiting for late-bind signal..."
              while [ ! -f $MOUNT_PATH/.ready ]; do sleep 0.05; done
              echo "Filestore volume mounted successfully!"
              ls -la $MOUNT_PATH/$SUB_DIR
              date >> $MOUNT_PATH/$SUB_DIR/session.txt
              sleep infinity
      volumes:
        - name: workspace-volume
          emptyDir: {}
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: late-bind-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: late-bind-template

次のようにマニフェストを適用します。

kubectl apply -f sandbox-latebind.yaml

サンドボックスを要求してストレージを動的にバインドする

削除ファイナライザー（agent.sandbox/storage-cleanup）を含む late-bind-claim.yaml という名前のクレームマニフェストを作成します。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: late-bind-session-1
  namespace: default
  finalizers:
    - agent.sandbox/storage-cleanup
spec:
  sandboxTemplateRef:
    name: late-bind-template

請求を適用します。

kubectl apply -f late-bind-claim.yaml

agent-volume-pvc.yaml という名前の PVC マニフェストを使用してボリュームを動的にプロビジョニングします。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: session-1-pvc
  namespace: default
spec:
  accessModes: [ReadWriteMany]
  storageClassName: volume-pool-sc
  resources:
    requests:
      storage: 1Gi

PVC を適用します。

kubectl apply -f agent-volume-pvc.yaml

割り当てられた Pod の UID、ノード、バッキング PV のエクスポートの詳細を取得します。

POD_NAME=$(kubectl get pods \
  -l extensions.agents.x-k8s.io/claimed-by=late-bind-session-1 \
  -o jsonpath='{.items[0].metadata.name}')
POD_UID=$(kubectl get pod "${POD_NAME}" -o jsonpath='{.metadata.uid}')
NODE_NAME=$(kubectl get pod "${POD_NAME}" -o jsonpath='{.spec.nodeName}')
PV_NAME=$(kubectl get pvc session-1-pvc -o jsonpath='{.spec.volumeName}')
NFS_IP=$(kubectl get pv "${PV_NAME}" \
  -o jsonpath='{.spec.csi.volumeAttributes.ip}')
NFS_PATH="/$(kubectl get pv "${PV_NAME}" \
  -o jsonpath='{.spec.csi.volumeAttributes.volume}')"

Pod ホストのノードデーモンにマウントシグナルを送信します。

DAEMON_POD=$(kubectl get pods -l app=storage-node-daemon \
  --field-selector spec.nodeName="${NODE_NAME}" \
  -o jsonpath='{.items[0].metadata.name}')
kubectl exec "${DAEMON_POD}" -c daemon -- python3 -c "
import urllib.request, json
payload = json.dumps({
    'action': 'bind_nfs',
    'pod_uid': '${POD_UID}',
    'volume_name': 'workspace-volume',
    'sub_dir': 'user_data',
    'nfs_server': '${NFS_IP}',
    'nfs_path': '${NFS_PATH}'
}).encode()
req = urllib.request.Request(
    'http://localhost:9090',
    data=payload,
    headers={'Content-Type': 'application/json'})
print(urllib.request.urlopen(req).read().decode())
"

ホストマウントがアクティブな間に早すぎるクリーンアップを防ぐため、要求された Pod に削除ファイナライザーを適用します。
```
kubectl patch pod "${POD_NAME}" --type=merge \
  -p '{"metadata":{"finalizers":["agent.sandbox/storage-cleanup"]}}'
```
注意: ホストレベルのマウントは標準の Kubelet ボリュームトラッキングをバイパスするため、ストレージのマウントを解除する前に Pod を削除すると、Kubelet のクリーンアップが失敗し、Device or resource busy エラーが発生します。SandboxClaim と Pod の両方にファイナライザーを適用すると、Kubernetes が Pod を削除する前に、オーケストレーターがストレージを安全にマウント解除できます。

実行中の Pod 内のボリュームマウントを確認します。

kubectl logs "${POD_NAME}" -c agent

出力は、Volume が正常にマウントされたことを示しています。

Waiting for late-bind signal...
Filestore volume mounted successfully!
drwxr-xr-x    2 1000     1000          4096 ... user_data

セッションを一時停止、再開する

エージェントセッションが終了するか、休止状態になると、オーケストレーターは、Kubernetes が Pod を終了または再利用できるようにする前に、ホストストレージをマウント解除する必要があります。

バックグラウンドで SandboxClaim の削除を開始します。ファイナライザのため、Kubernetes は削除対象の要求をマークしますが、Pod の終了を一時停止します。
```
kubectl delete sandboxclaim late-bind-session-1 --wait=false
```

ホストノードで NFS 共有のマウントを解除します。

kubectl exec "${DAEMON_POD}" -c daemon -- python3 -c "
import urllib.request, json
payload = json.dumps({
    'action': 'unbind',
    'pod_uid': '${POD_UID}',
    'volume_name': 'workspace-volume',
    'sub_dir': 'user_data'
}).encode()
req = urllib.request.Request(
    'http://localhost:9090',
    data=payload,
    headers={'Content-Type': 'application/json'})
print(urllib.request.urlopen(req).read().decode())
"

SandboxClaim と Pod の両方からファイナライザを削除して、終了を完了します。

kubectl patch sandboxclaim late-bind-session-1 --type=merge \
  -p '{"metadata":{"finalizers":[]}}'
kubectl patch pod "${POD_NAME}" --type=merge \
  -p '{"metadata":{"finalizers":[]}}'

セッションを後で再開するには、新しい事前ウォーミングされた Pod を要求し、既存の PVC（session-1-pvc）を使用してバインドリクエストを送信します。新しいサンドボックス Pod は、保存されたワークスペースの状態にすぐにアクセスできます。

本番環境の考慮事項とカスタムコントローラの設計

このドキュメントの手動コマンドは、動的遅延バインディングの低レベルのメカニズムを示しています。このアーキテクチャを本番環境で確実に実行するには、アプリケーションのセッションライフサイクルに合わせてカスタマイズされたカスタム Kubernetes コントローラまたはプラットフォームオーケストレーターを開発する必要があります。

本番環境のコントローラとノードデーモンを設計する際は、次のアーキテクチャパターンを実装します。

調整とファイナライザーのライフサイクルを自動化する

ストレージノードデーモンは、標準の Kubernetes Container Storage Interface（CSI）ライフサイクル管理の外部でホストレベルのマウントを実行するため、Kubelet は Pod の emptyDir 内のアクティブなマウントを認識しません。マウントがアクティブな状態で Pod が削除されると、Kubelet は emptyDir ディレクトリを削除できず、Device or resource busy エラーが発生し、Pod が Terminating 状態のままになります。

カスタムコントローラは、ファイナライザー（agent.sandbox/storage-cleanup など）を使用して厳格な状態マシンを自動化する必要があります。

クレームの作成とバインディング:
- 作成時にすべての SandboxClaim に静的ファイナライザーをアタッチします。
- Kubernetes API で SandboxClaim のステータス更新を監視します。クレームがウォームプール Pod にバインドされたら、割り当てられた pod_uid、nodeName、バッキング Filestore ボリューム属性を抽出します。
- 認証済みの bind リクエストを、ターゲットノードで実行されているストレージノードデーモンに送信します。
- 実行中の Pod オブジェクトに動的ファイナライザーを追加するために、直ちにパッチを適用します。SandboxTemplate 仕様では静的 Pod ファイナライザーがサポートされていないため、Pod が削除されても SandboxClaim がアクティブな状態が続くノードのドレインイベントやリスケジューリングイベント中に Pod を保護するには、Pod を動的にパッチ適用する必要があります。
正常終了と削除の処理:
- SandboxClaim リソースと Pod リソースの両方で deletionTimestamp を監視します。
- 削除または強制排除が検出されたら、ノードデーモンの unbind エンドポイントを呼び出して、ホストディレクトリ（umount -l）をクリーンにマウント解除します。
- アンマウントが成功し、保留中の書き込みがすべてフラッシュされたことを確認してから、Pod と SandboxClaim にパッチを適用してファイナライザーを削除します。これにより、グレースフルな削除、GKE ノードのアップグレード、Spot VM のプリエンプション、メモリ不足（OOM）による強制終了など、クリーンな削除を実現できます。

ストレージノードデーモンを保護して強化する

kubectl exec を認証済み API に置き換えます。本番環境では、kubectl exec を使用したり、デーモンを localhost にバインドしたりしないでください。相互 TLS（mTLS）または Kubernetes ServiceAccount トークン認証で保護されたクラスタネットワークを介して専用の gRPC または HTTPS エンドポイントを公開するように、ストレージノードデーモンを構成します。
デーモン Namespace とネットワークアクセスを分離する: 制限付きの管理 Namespace（default やテナント Namespace ではなく、sandbox-storage-system など）に特権 storage-node-daemon DaemonSet をデプロイします。カスタムコントローラ Pod からのみデーモン API への上り（内向き）を許可し、サンドボックス化されたエージェント Pod からのすべてのトラフィックをブロックする Kubernetes NetworkPolicy ルールを適用します。
事前作成されたコンテナイメージを使用する: initContainer で実行時に nfs-common などのパッケージをインストールしないようにします。必要なマウントユーティリティがすべてプリインストールされた、ビルド済みの不変コンテナイメージを使用して、ノードの起動遅延と外部リポジトリの依存関係を解消します。

ストレージ割り当てとマルチテナント分離を適用する

エージェントごとのストレージ使用量をモニタリングする: 共有 ReadWriteMany（RWX）Filestore ボリュームのサブディレクトリを emptyDir に動的にバインドマウントする場合、標準の Kubernetes emptyDir.sizeLimit 設定では、マウントされた NFS パスにエージェントごとのストレージ割り当てを適用できません。単一の暴走エージェントが共有ボリュームを使い果たしてサービス拒否（DoS）を引き起こすのを防ぐには、オーケストレーターでディレクトリ割り当てのモニタリングを実装するか、ボリュームプールを使用して専用ボリュームをプロビジョニングします。
さまざまなワークスペースアクセスモードに合わせてマウントペイロードを調整する: コントローラは、ノードデーモンに送信されるパラメータを変更することで、複数のエージェントストレージトポロジをサポートできます。
- プライベート分離ワークスペース: 一意のテナントサブディレクトリまたは専用 PVC を、読み取り / 書き込み権限を持つ単一のサンドボックス Pod にバインドします。
- コラボレーションワークスペース: リアルタイムのファイル共有のために、複数の連携エージェント Pod 間で同じ共有 RWX サブディレクトリを同時にバインドします。
- 探索ブランチワークスペース: ベーステンプレートディレクトリを読み取り専用（ro）としてマウントし、エージェントがゴールデンコピーを変更せずに共有アセットを読み取れるようにします。同時に、新しい書き込みを別の書き込み可能なスクラッチパスまたは復元時のコピーディレクトリに転送します。

ポイントインタイムスナップショットとクリーンアップを調整する

スナップショットの前に書き込みの静止を実現する: データの破損なしに一貫性のある特定の時点のワークスペーススナップショットを取得するには、ワークスペースディレクトリをアーカイブする前、または Filestore スナップショットをトリガーする前に、アンバインドワークフローを開始（またはファイルシステムバッファをフラッシュ）して、アクティブな書き込みを一時停止する必要があります。
テナントのプロビジョニング解除を自動化する: ユーザーセッションまたはワークスペースが完全に期限切れになったら、コントローラがまずすべてのノードでアクティブなマウントをバインド解除してから、非同期バックグラウンドタスクを実行して、テナントの永続ディレクトリをバッキングボリュームから削除するようにします。

動的ファイナライザー管理、マルチテナント分離、スナップショット復元ワークフローを示す完全なリファレンス実装については、GitHub の GKE Sandbox の遅延バインディングストレージの例をご覧ください。

次のステップ

静的 Agent Sandbox 統合について説明します。
セルフマネージド GKE ワークロードをデプロイします。
ボリュームプールの作成と管理の方法を学習する。

GKE Agent Sandbox の動的ストレージの遅延バインディングで Filestore エージェント ボリュームを使用する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。