このページの一部またはすべての情報は、S3NS の Cloud de Confiance に適用されない場合があります。詳細については、Google Cloud との違いをご確認ください。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cloud Storage FUSE プロファイルを使用してパフォーマンスチューニングを自動化する

Autopilot Standard

このドキュメントでは、Google Kubernetes Engine（GKE）で Cloud Storage FUSE プロファイルを使用して、Cloud Storage FUSE CSI ドライバのパフォーマンスを自動的に調整し、AI/ML ワークロードのデータアクセスを高速化する方法について説明します。

Cloud Storage FUSE プロファイルは、重要なパフォーマンスチューニングプロセスを自動化します。設定を手動で調整する代わりに、CSI ドライバを構成する事前定義されたプロファイルを適用できます。AI/ML アプリケーションの場合、これらのプロファイルを使用すると、運用オーバーヘッドを削減しながら、トレーニング時間と推論時間を短縮できます。

このドキュメントは、ストレージチューニングの専門知識がなくてもアプリケーションのパフォーマンスを改善したいアプリケーションデベロッパーと ML エンジニアを対象としています。一般的なロールの詳細については、GKE ユーザーの一般的なロールとタスクをご覧ください。

このドキュメントを読む前に、Cloud Storage、Kubernetes、Cloud Storage FUSE CSI ドライバの基本を理解しておいてください。また、Cloud Storage FUSE CSI ドライバを使用するための要件も確認してください。

Cloud Storage FUSE プロファイルを使用するメリット

AI/ML ワークロードのパフォーマンス調整を自動化するために、Cloud Storage FUSE プロファイルは事前定義された Cloud Storage FUSE 構成を使用し、GKE 固有の追加設定を適用します。これらの設定は、Cloud Storage FUSE のパフォーマンス調整のベストプラクティスに基づいています。事前定義されたプロファイルを使用すると、次のメリットがあります。

パフォーマンスチューニングの簡素化: 事前定義された Cloud Storage FUSE プロファイルを使用して、トレーニング、サービング、チェックポイントなどの一般的な AI/ML ワークロードに最適化された構成を適用します。
リソースを認識した動的な最適化: Cloud Storage FUSE プロファイルを使用すると、CSI ドライバは、サイズ、オブジェクト数、ロケーションタイプなどのバケットまたはサブディレクトリの特性、サイドカーの上限、ノードの利用可能なリソースに基づいて、キャッシュサイズを自動的に調整し、最適なキャッシュメディア（RAM やローカル SSD など）を選択できます。
読み取りパフォーマンスの向上: gcsfusecsi-serving プロファイルを使用すると、GKE は Rapid Cache を自動的に有効にして、サービングワークロードの読み取りパフォーマンスを向上させます。
パフォーマンスチューニングの分析情報: 環境からの入力シグナルと、ドライバによって適用された結果の構成の詳細を示す構造化されたログを通じて、自動チューニングの決定に関する分析情報を取得できます。詳細については、推奨事項の分析情報を表示するをご覧ください。

Cloud Storage FUSE のベストプラクティスの進化に伴い、新しい GKE リリースを通じてプロファイルが更新されます。

制限事項

Cloud Storage FUSE CSI エフェメラルボリュームで Cloud Storage FUSE プロファイルを使用することはできません。
プロファイルは、Kubernetes ServiceAccount がアクセスできるすべてのバケットをマウントするためにアンダースコア（_）を指定する動的マウントをサポートしていません。
カスタムの非公開サイドカーイメージでサイドカーイメージをオーバーライドすることはできません。詳細については、サイドカーコンテナのプライベートイメージを構成するをご覧ください。

要件

GKE クラスタでバージョン 1.35.1-gke.1616000 以降を実行している必要があります。
クラスタで Cloud Storage FUSE CSI ドライバが有効になっている必要があります。新しいクラスタを作成する場合、または既存のクラスタでドライバを有効にする場合は、ドキュメントの次の手順を参照して、GKE 用の Cloud Storage FUSE CSI ドライバを設定します。

費用

Cloud Storage FUSE CSI ドライバに関連する標準の GKE と Cloud Storage の費用に加えて、Cloud Storage FUSE プロファイルを使用すると、次の費用が発生します。

バケットスキャンの費用

Cloud Storage FUSE プロファイルは、バケットまたはサブディレクトリのバックグラウンドスキャンを実行します。デフォルトでは、このスキャンは 7 日ごとに実行されます。バケットのスキャンでは、オブジェクトのリストに対して Cloud Storage クラス A オペレーションの料金が発生します。

Rapid Cache の費用

gcsfusecsi-serving プロファイルでは、Rapid Cache が自動的に有効になります。Rapid Cache の料金は、Cloud Storage Rapid Cache の料金に従って請求されます。キャッシュインスタンスが不要になったときに料金が発生しないようにするには、費用管理をご覧ください。

始める前に

作業を始める前に、次のタスクが完了していることを確認してください。

Cloud Storage API と Google Kubernetes Engine API を有効にします。

API を有効にする

このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。gcloud CLI をインストール済みの場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region プロパティを設定してください。主にゾーンクラスタを使用する場合は、代わりに compute/zone を設定します。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。クラスタのロケーションが設定したデフォルトと異なる場合は、特定のコマンドでロケーションの指定が必要になることがあります。

ニーズに適した Cloud de Confiance by S3NS リージョンを選択します。パフォーマンスと費用を最適化するために、GKE クラスタと Cloud Storage バケットを同じリージョンに作成することをおすすめしますが、gcsfusecsi-serving プロファイルを使用する場合や、Rapid Cache を有効にする場合は、同じリージョンに作成することが必須です。
AI/ML ワークロードのデータセット、モデル、チェックポイントを含む既存の Cloud Storage バケットがあることを確認します。バケットを作成する必要がある場合は、バケットを作成するをご覧ください。

パフォーマンスプロファイルを選択する

ワークロードに最適なプロファイルを選択します。各プロファイルは、クラスタにプリインストールされた StorageClass に対応します。Cloud Storage FUSE プロファイルの詳細な定義については、対応する StorageClass 構成リファレンスをご覧ください。

プロフィール	StorageClass 名	最適な用途	主な機能
トレーニング	`gcsfusecsi-training`	高スループットの読み込みを利用できます。	大規模なデータセットでのトレーニング中に GPU と TPU のデータレイテンシを最適化します。
チェックポイント処理	`gcsfusecsi-checkpointing`	高スループットの書き込み	大きなチェックポイントの保存に必要な時間を最小限に抑え、トレーニングの一時停止を短縮します。
サービス提供	`gcsfusecsi-serving`	データアクセスとキャッシュ保存	読み取りオペレーションを高速化するために、Rapid Cache がデフォルトで有効になっています。

次のコマンドを実行すると、クラスタにインストールされている StorageClass を確認できます。

kubectl get sc -l gke-gcsfuse/profile=true

IAM 権限を構成する

Cloud Storage バケットの分析と Rapid Cache の管理を行う権限を GKE サービスエージェントに付与します。

このセクションのコマンドを実行する際に、次のプレースホルダを置き換えます。

GCS_PROJECT: Cloud Storage バケットを含むプロジェクト ID。
PROJECT_NUMBER: GKE クラスタプロジェクトのプロジェクト番号。
BUCKET_NAME: Cloud Storage バケットの名前。

プロファイルと使用ニーズに合ったオプションを次のいずれかから選択します。

オプション A: カスタムロール（推奨）

このオプションは、サービングプロファイルの場合、または Rapid Cache が使用されている場合に必要です。サービングプロファイルを使用する場合や、他のプロファイルで Rapid Cache を手動で有効にする場合は、そのキャッシュを管理する権限を付与する必要があります。

オブジェクトのスキャンと Rapid Cache キャッシュの作成を許可するカスタム IAM ロールを作成します。

gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

特定のバケットの GKE サービスエージェントにカスタムロールをバインドします。

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

オプション B: トレーニングプロファイルとチェックポイントプロファイルの標準ロール

トレーニングプロファイルまたはチェックポイントプロファイルのみを使用し、Rapid Cache を使用する予定がない場合は、次のコマンドを実行します。

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Cloud Storage FUSE プロファイルを使用してワークロードをデプロイする

Cloud Storage FUSE プロファイルを使用してワークロードをデプロイする手順は次のとおりです。

Cloud Storage FUSE プロファイルの StorageClass のいずれかを参照する PersistentVolume（PV）マニフェストを作成します。
```
apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
```
次のように置き換えます。
- STORAGECLASS_NAME: 使用するプロファイルの StorageClass 名。値は gcsfusecsi-training、gcsfusecsi-checkpointing、または gcsfusecsi-serving にする必要があります。
- BUCKET_DIR_PATH: （省略可）特定のディレクトリをマウントする場合は、Cloud Storage バケット内のパス。指定すると、GKE はこのパスをスキャンして最適化します。省略すると、GKE はバケット全体をスキャンします。
- BUCKET_NAME: Cloud Storage バケットへのアクセスを構成するときに指定した Cloud Storage バケット名。

PV と同じ StorageClass をリクエストする PersistentVolumeClaim（PVC）を作成します。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

次のように置き換えます。

NAMESPACE: Pod をデプロイする Namespace。
STORAGECLASS_NAME: PV に記載されている StorageClass 名。

Deployment で PVC を使用します。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

次のように置き換えます。

NAMESPACE: Pod をデプロイする Namespace。
KSA_NAME: Cloud Storage バケットへのアクセスを構成するときに作成した Kubernetes ServiceAccount の名前。

デプロイ後、CSI ドライバは、GPU や TPU、メモリ、ローカル SSD、バケットまたはサブディレクトリのサイズ、サイドカーのリソース上限など、ノードのリソースに基づいて最適なキャッシュサイズとマウントオプションを自動的に計算します。

自動最適化を確認する

GKE バックグラウンドプロセスはバケットを自動的に分析し、Rapid Cache を同期します（使用されている場合）。

バケットスキャンとキャッシュの両方のステータスを確認する

PV を作成したら、次の手順でバケットスキャンとキャッシュの両方のステータスを確認します。Pod がデプロイされるまで待つ必要はありません。

PV のステータスを確認します。
```
kubectl describe pv my-pv
```

出力に ScanOperationSucceeded イベントが表示されていることを確認します。出力は次のようになります。

Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

gcsfusecsi-serving プロファイルを使用する場合は、キャッシュ保存レイヤの準備が完了した後に AnywhereCacheSyncSucceeded イベントが表示されることを確認します。出力は次のようになります。
```
Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running
```
注: Rapid Cache の作成には数分から数時間かかることがあります。この間、ワークロードはブロックされず、キャッシュが動作するまでバケットからデータを直接読み取ることができます。詳細については、キャッシュを作成するをご覧ください。

PV アノテーションがスキャン結果で更新されていることを確認します。

gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

ポッドのステータスを確認する

Pod をデプロイしたら、次のコマンドを実行します。

kubectl get pods -n NAMESPACE

NAMESPACE は、Pod をデプロイした Namespace に置き換えます。

これで、Pod は RUNNING ステータスになり、パフォーマンスのベストプラクティスが自動的に適用されます。Pod のステータスが SchedulingGated の場合は、GKE がバケットまたはサブディレクトリをスキャンしていることを示します。この状態は、CSI コントローラがスキャンを完了して PV を更新するまで続きます。

Pod の起動後にドライバによってロギングされた特定のチューニングの決定事項を確認するには、推奨事項の分析情報を表示するをご覧ください。

エラーが発生した場合は、トラブルシューティングのセクションをご覧ください。

StorageClass 構成リファレンス

このセクションでは、プリインストールされた Cloud Storage FUSE プロファイルの StorageClass マニフェストと、プロファイルで使用されるマウントオプションとパラメータの詳細なリファレンスを提供します。これらの構成により、gcsfuse.csi.storage.gke.io ドライバは AI/ML ワークロードのパフォーマンスチューニングとリソース管理を自動化できます。

トレーニング

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

チェックポイント処理

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

サービス提供

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

プロファイルでは、gcsfuse.csi.storage.gke.io ドライバに次のマウントオプションとパラメータを使用します。

mountOptions:
- profile: AI/ML ワークロード用に調整された事前定義された Cloud Storage FUSE 最適化のセットを適用します。プリインストールされたプロファイルの有効な値は、aiml-training、aiml-checkpointing、aiml-serving です。
- read_ahead_kb: 先読みバッファのサイズをキロバイト（KB）単位で指定します。このオプションを使用すると、Cloud Storage FUSE が Cloud Storage からデータをプリフェッチできるため、シーケンシャルアクセスパターンの読み取りパフォーマンスが向上する可能性があります。
- file-cache:max-size-mb: Serving プロファイルの場合、ファイルキャッシュの最大サイズ（MiB 単位）を指定します。モデルが通常 GPU または TPU メモリに 1 回だけ読み込まれるサービングワークロードでは、このパラメータは 0 に設定され、ローカル Cloud Storage FUSE ファイルキャッシュが無効になります。これにより、冗長なディスク I/O を防ぎ、ローカルストレージを節約できます。
- read:enable-buffered-read: Serving プロファイルの場合、Cloud Storage FUSE が独自の内部バッファを管理できるようにします。これにより、アプリケーションとカーネル間の高コストな小さなシステムコールの数を減らすことができます。
- read:global-max-blocks: サービングプロファイルの場合、バッファリングされた読み取りに使用される同時メモリブロックの合計数を制限します。このオプションは、複数のリクエストを処理するときに FUSE プロセスが使用可能なすべての RAM を消費するのを防ぐのに役立ちます。
parameters:
- skipCSIBucketAccessCheck: "true" に設定すると、CSI ドライバは最初のバケットアクセスチェックをスキップします。このパラメータは、セキュリティトークンサービスへの呼び出しを減らし、割り当ての問題を回避するのに役立ちます。
- gcsfuseMetadataPrefetchOnMount: "true" に設定すると、ボリュームがマウントされるとすぐに、Cloud Storage からローカルキャッシュへのオブジェクトメタデータのprefetchingを開始するように CSI ドライバに指示します。このパラメータを使用すると、ファイルへの初回アクセスを高速化できます。
- fuseFileCacheMediumPriority: Cloud Storage FUSE のファイルキャッシュで使用されるストレージメディアの優先順位を定義します。これにより、GPU、TPU、汎用ノードを持つノードに対して異なる設定を指定できます。メディアオプションには、ram と lssd（ローカル SSD が使用可能で有効になっている場合）があります。
- fuseMemoryAllocatableFactor: ノードの割り当て可能な合計メモリとサイドカーのメモリ上限を基準として、Cloud Storage FUSE キャッシュが使用できる最大メモリを制限する割合を文字列形式で指定します。
- fuseEphemeralStorageAllocatableFactor: ノードの一時ストレージ（ファイルキャッシュ用のローカル SSD など）の Cloud Storage FUSE キャッシュ使用量を、ノードの割り当て可能な一時ストレージまたはキャッシュ用に制限されたサイドカーの一時ストレージに対して制限します。
- bucketScanResyncPeriod: Cloud Storage バケットに加えられた変更を検出するために PV が再スキャンされる時間間隔を設定します。
- bucketScanTimeout: 単一のバケットスキャンオペレーションで許可される最大期間。スキャンがこの時間を超えると、部分的な結果が使用されることがあります。
- anywhereCacheZones: Rapid Cache キャッシュが作成されるサポートされているゾーンのカンマ区切りリストを指定します（例: "us-central1-a,us-central1-b"）。クラスタで使用可能なすべてのゾーンを使用するには、値として "*" を使用します。これを "none" に設定するか、未指定のままにすると、Rapid Cache が無効になります。
- anywhereCacheTTL: Rapid Cache キャッシュに保存されたデータの有効期間（TTL）。最後のアクセスから測定されます。この値を変更すると、既存の Rapid Cache インスタンスが新しい TTL で更新されます。
- anywhereCacheAdmissionPolicy: 読み取りミス（リクエストされたデータがキャッシュに見つからない場合）の後に、Rapid Cache キャッシュにデータを追加するタイミングを決定します。オプションには、最初の読み取りミスでデータを許可する "admit-on-first-miss" と、同じオブジェクトの 2 回目の読み取りミスでのみデータを許可する "admit-on-second-miss" があります。この値を変更すると、既存の Rapid Cache インスタンスが新しいポリシーで更新されます。

省略可: プロファイル構成を微調整する

プロファイルの基本構成のメリットを維持しながら、プロファイル内の特定の設定をカスタマイズできます。新しい StorageClass を作成せずにプロファイルを調整するには、次のオプションを使用します。

マウントオプションとパラメータをオーバーライドする

特定の動作を変更するには、PV の spec.mountOptions フィールドにマウントオプションを追加するか、spec.csi.volumeAttributes フィールドに CSI パラメータを追加します。GKE は、プロファイルのデフォルトの上に手動設定を適用します。

次の例は、read_ahead_kb マウントオプションをオーバーライドして、Serving プロファイルで gcsfuseMetadataPrefetchOnMount パラメータを無効にする方法を示しています。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

一般的なユースケースは次のとおりです。

トレーニングプロファイルで Rapid Cache を有効にするには、PV 仕様に anywhereCacheZones パラメータを直接追加します。
特定のワークロードの固有の要件を満たすために、read_ahead_kb サイズの増加など、特定の Cloud Storage FUSE の動作を調整する。

キャッシュサイズを手動で構成する場合は、次の点を考慮してください。

手動でキャッシュサイズを指定すると、その特定のコンポーネントの自動動的サイズ設定のみがオーバーライドされます。動的サイジングは、残りのリソース予算内で、他のすべてのコンポーネントに対してベストエフォートで継続されます。
metadata-cache:stat-cache-max-size-mb などの metadata-cache オプションまたは file-cache オプションを設定しても、他のキャッシュタイプの自動計算は無効になりません。
file-cache:max-size-mb を手動で指定する場合は、カスタム読み取りキャッシュボリュームも構成する必要があります。これにより、カスタムキャッシュサイズに十分な容量を持つストレージメディアが明示的に定義されます。

アノテーションを使用してバケットスキャンをバイパスする

アノテーションを使用して独自のオブジェクト数とサイズ指標を指定すると、バケットの自動スキャンプロセスをバイパスできます。CSI ドライバは、これらの値を使用して、バケットをスキャンせずに最適なパフォーマンス構成を計算します。

次の例は、特定の指標アノテーションとともに gke-gcsfuse/bucket-scan-status: "override" アノテーションを PV に追加する方法を示しています。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

一般的なユースケースは次のとおりです。

バケットのサイズとオブジェクト数がすでにわかっている場合（特にデータがほとんど変更されない推論ワークロードの場合）、起動時のスキャン時間を短縮できます。
Cloud Storage API が一時的に使用できない場合、これらのアノテーションは、基盤となるサービスが修正されている間、パフォーマンスを維持するのに役立ちます。

トラブルシューティング

次の情報を使用して、Cloud Storage FUSE プロファイルのステータスをモニタリングし、バケットスキャンとキャッシュ同期中に発生する一般的な問題を解決します。

構成パラメータが無効です（`InvalidArgument`）

マニフェストで指定された 1 つ以上のパラメータが無効であるため、バックグラウンド最適化タスクを開始できませんでした。

症状

PV に、rpc error: code = InvalidArgument を含むメッセージを含む ScanOperationStartError イベントまたは AnywhereCacheSyncError イベントが表示されます。次に例を示します。

Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

原因

PV の spec.csi.volumeAttributes フィールドの 1 つ以上のパラメータの形式が正しくないか、システムが解析できない値が含まれています。

解決策

PV マニフェストで無効なパラメータ値を修正し、PV を再デプロイします。すべての期間値（bucketScanTimeout など）が正しい形式（2m や 10m など）を使用しており、プロファイル固有の設定がすべて有効なサポート対象の値と一致していることを確認します。

Cloud Storage バケットのスキャン中に権限が拒否された

GKE は、必要なパフォーマンス分析を実行するために、指定された Cloud Storage バケットにアクセスできません。

症状

PV に ScanOperationStartError イベントが表示され、呼び出し元に storage.buckets.get アクセス権がないことを示す Error 403: Forbidden メッセージが表示されます。

原因

GKE サービスエージェントに必要な IAM 権限がないか、バケット名が正しくありません。

解決策

PV の volumeHandle フィールドのバケット名が正しいことと、バケットが存在することを確認します。
特定のバケットの service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com ID に GKE サービスエージェントの権限が付与されていることを確認します。詳細については、IAM 権限を構成するをご覧ください。

Rapid Cache のロケーションが一致しない

リクエストされたゾーンがバケットのロケーションと互換性がないため、Rapid Cache キャッシュを作成できませんでした。

症状

PV に、メッセージ Invalid zone. Rapid Cache isn't available in the requested zone. を含む AnywhereCacheSyncWarning イベントが表示されます。

原因

Rapid Cache キャッシュは、バケットのリージョンロケーション内のゾーンに作成する必要があります。このエラーは通常、GKE クラスタと Cloud Storage バケットが異なるリージョンにある場合に発生します。

解決策

Cloud Storage バケットを GKE クラスタのロケーションと一致するリージョンに移動し、PV を再デプロイします。

バケットスキャンのタイムアウト

Cloud Storage バケットの分析に構成済みのタイムアウトよりも時間がかかったため、最適化結果が一部のみになりました。

症状

PV には ScanOperationTimedOut イベントが表示されます。PV には、オブジェクト数と合計サイズの部分的な結果が注釈として付加されます。

原因

バケットに非常に多くのオブジェクト（通常は数百万個）が含まれており、デフォルトの 2 分のタイムアウト内に完全に一覧表示できません。

解決策

PV の spec.csi.volumeAttributes セクションの bucketScanTimeout フィールドに、より大きな値を設定します（例: 10m）。
バケットサイズが静的な場合は、オブジェクトの数とサイズを手動で指定して、スキャンをバイパスします。

メモリ予算によって上限が設定されたメタデータキャッシュ

ドライバは、ノードで使用可能なリソース内に収まるようにメタデータキャッシュのサイズを制限していました。これにより、パフォーマンスが低下する可能性があります。

症状

ログには、必要なメタデータ統計情報キャッシュサイズが使用可能な Cloud Storage FUSE メモリバジェットに制限されたことを示すメッセージが含まれています。

原因

バケット内のオブジェクト数のメタデータキャッシュが、Cloud Storage FUSE サイドカーに割り当てられたメモリまたはノードの利用可能なメモリを超えています。

解決策

only-dir マウントオプションを使用して、オブジェクトの少ない小さなサブディレクトリにボリュームの範囲を設定します。
Cloud Storage FUSE サイドカーコンテナのメモリ上限を引き上げます。
- サイドカーの上限がすでに十分な場合は、割り当て可能なメモリが多いノードタイプを使用します。

リソースの上限によりファイルキャッシュが無効になりました

GKE は、十分な容量を備えた適切なストレージメディアが見つからなかったため、ローカルファイルキャッシュを無効にしました。

症状

ログに「No suitable file cache medium found or requirement exceeded limits for all options」という警告が表示されます。

原因

計算されたファイルキャッシュサイズが、使用可能なノードの RAM と使用可能なローカル SSD ストレージの両方を超えています。

解決策

only-dir マウントオプションを使用して、オブジェクトの少ない小さなサブディレクトリにボリュームの範囲を設定します。
Cloud Storage FUSE サイドカーのリソース上限を引き上げます。
メモリ容量が大きいノードタイプを使用するか、ノードプールでローカル SSD を有効にします。

PersistentVolume イベントを使用してステータスをモニタリングする

GKE は、主要な構成イベントとエラーを PV に記録します。これらのイベントを確認するには、次のコマンドを実行します。

kubectl describe pv PV_NAME

バケットスキャンが成功すると、ScanOperationSucceeded イベントが表示されます。gcsfusecsi-serving プロファイルを使用すると、キャッシュ保存レイヤが動作した後に AnywhereCacheSyncSucceeded イベントが表示されます。

CSI ドライバログを使用してステータスをモニタリングする

Cloud Storage FUSE CSI ドライバは、構成の決定とパフォーマンスに関する分析情報を詳細に記録します。Cloud Logging でこれらのログを表示するには、次のクエリを使用します。

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

推奨事項の分析情報を表示する

自動チューニングロジックによって行われた特定の入力シグナルと決定を理解するには、CSI ドライバログで GCSFuseCSIRecommendation 文字列を検索します。結果の JSON ペイロードには、次のような詳細な指標が含まれます。

inputSignals: バケットオブジェクトの数、データの合計サイズ、使用可能なノードリソース（RAM とエフェメラルストレージ）。
decision: 最終的に計算されたキャッシュサイズと、選択されたストレージメディア（ram または lssd）。

{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

クリーンアップ

このガイドで作成したリソースについて Cloud de Confiance by S3NS アカウントに課金されないようにするには、次の手順を行います。

Deployment を削除します。
```
kubectl delete deployment my-deployment -n NAMESPACE
```
NAMESPACE は、Deployment を作成した Kubernetes Namespace に置き換えます。
PersistentVolumeClaim を削除します。
```
kubectl delete pvc my-pvc -n NAMESPACE
```
NAMESPACE は、PVC を作成した Kubernetes Namespace に置き換えます。
PersistentVolume を削除します。
```
kubectl delete pv my-pv
```
gcsfusecsi-serving プロファイルを使用した場合、または Rapid Cache を手動で有効にした場合は、キャッシュを無効にするの手順に沿って、キャッシュインスタンスの料金が発生しないようにします。

次のステップ

Cloud Storage FUSE CSI ドライバの詳細を確認する。
パフォーマンスを向上させるために Cloud Storage FUSE CSI ドライバを手動で最適化する方法を確認する。

Cloud Storage FUSE プロファイルを使用してパフォーマンス チューニングを自動化する

Cloud Storage FUSE プロファイルを使用するメリット

制限事項

要件

費用

バケット スキャンの費用

Rapid Cache の費用

始める前に

パフォーマンス プロファイルを選択する

IAM 権限を構成する

オプション A: カスタムロール（推奨）

オプション B: トレーニング プロファイルとチェックポイント プロファイルの標準ロール

Cloud Storage FUSE プロファイルを使用してワークロードをデプロイする

自動最適化を確認する

バケット スキャンとキャッシュの両方のステータスを確認する

ポッドのステータスを確認する

StorageClass 構成リファレンス

トレーニング

チェックポイント処理

サービス提供

省略可: プロファイル構成を微調整する

マウント オプションとパラメータをオーバーライドする

アノテーションを使用してバケット スキャンをバイパスする

トラブルシューティング

構成パラメータが無効です（InvalidArgument）

Cloud Storage バケットのスキャン中に権限が拒否された

Rapid Cache のロケーションが一致しない

バケット スキャンのタイムアウト

メモリ予算によって上限が設定されたメタデータ キャッシュ

リソースの上限によりファイル キャッシュが無効になりました

PersistentVolume イベントを使用してステータスをモニタリングする

CSI ドライバログを使用してステータスをモニタリングする

推奨事項の分析情報を表示する

クリーンアップ

次のステップ

Cloud Storage FUSE プロファイルを使用してパフォーマンスチューニングを自動化する

バケットスキャンの費用

パフォーマンスプロファイルを選択する

オプション B: トレーニングプロファイルとチェックポイントプロファイルの標準ロール

バケットスキャンとキャッシュの両方のステータスを確認する

マウントオプションとパラメータをオーバーライドする

アノテーションを使用してバケットスキャンをバイパスする

構成パラメータが無効です（`InvalidArgument`）

バケットスキャンのタイムアウト

メモリ予算によって上限が設定されたメタデータキャッシュ

リソースの上限によりファイルキャッシュが無効になりました