Cloud Storage バケットを永続ボリュームとしてマウントする

このガイドでは、Cloud Storage バケットを基盤とする Kubernetes 永続ボリュームを使用して、Google Kubernetes Engine（GKE）で Kubernetes Pod のストレージ リソースを管理する方法について説明します。PersistentVolume に精通していて、このリソースタイプに依存する既存のデプロイメントとの整合性を維持したい場合は、このストレージ オプションの使用を検討してください。

このガイドは、GKE アプリケーションのストレージ管理を簡素化したいプラットフォームの管理者とオペレーターを対象としています。

このページを読む前に、Kubernetes 永続ボリューム、Kubernetes Pod、Cloud Storage バケットについて理解しておいてください。

Kubernetes 永続ボリュームの経験がなくても使用できる、合理化された Pod ベースのインターフェースが必要な場合は、Cloud Storage バケットを CSI エフェメラル ボリュームとしてマウントするをご覧ください。

始める前に

次の前提条件を満たしていることを確認してください。

• Cloud Storage FUSE CSI ドライバの要件と制限事項を理解する。
• Cloud Storage バケットを作成する
• Cloud Storage FUSE の CSI ドライバを有効にする
• Cloud Storage バケットへのアクセスを構成する

Cloud Storage バケットの永続ボリュームの仕組み

静的プロビジョニングを使用して、基盤となるストレージ システムの詳細を含む 1 つ以上の PersistentVolume オブジェクトを作成します。クラスタ内の Pod は、PersistentVolumeClaims を通じてストレージを消費できます。

Cloud Storage バケットを基盤とする永続ボリュームを使用するには、次のオペレーションが必要です。

1. ストレージの定義: 使用する CSI ドライバや必要なパラメータなど、GKE クラスタで PersistentVolume を定義します。Cloud Storage FUSE CSI ドライバの場合は、バケット名とその他の関連情報を指定します。

   必要に応じて、ファイル キャッシュ機能を使用して CSI ドライバのパフォーマンスを微調整できます。ファイル キャッシュを使用すると、頻繁にアクセスされる Cloud Storage ファイルを高速ローカル ディスクにキャッシュ保存することで、GKE アプリのパフォーマンスを向上させることができます。

   また、並列ダウンロード機能を使用して、Cloud Storage からの大規模なファイルの読み取りを高速化し、マルチスレッド ダウンロードを実現できます。この機能を使用すると、特にサイズが 1 GB を超える読み取りでモデルの読み込み時間を短縮できます。

2. ドライバの呼び出し: PersistentVolumeClaim が PersistentVolume の仕様に一致するストレージをリクエストすると、GKE は Cloud Storage FUSE CSI ドライバを呼び出します。

3. バケットのマウント: CSI ドライバは、リクエスト元の Pod がスケジュールされているノードにバケットをマウントします。これにより、バケットの内容が Pod のローカル ファイル システムのディレクトリとして Pod からアクセスできるようになります。ファイル システムでバケットのマウント方法を微調整するには、マウント オプションを使用します。ボリューム属性を使用して、Cloud Storage FUSE CSI ドライバの特定の動作を構成することもできます。

4. 再アタッチ: Pod が再起動するか、別のノードに再スケジュールされると、CSI ドライバは同じバケットを新しいノードに再マウントし、データのアクセスを確保します。

PersistentVolume を作成する

1. 次の仕様で PersistentVolume マニフェストを作成します。

   Pod

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class  
     mountOptions:
       - implicit-dirs
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE  
   

   次の値を置き換えます。

   • NAMESPACE: Pod をデプロイする Kubernetes Namespace。
   • BUCKET_NAME: Cloud Storage バケットへのアクセスを構成するときに指定した Cloud Storage バケット名。アンダースコア（_）を指定すると、Kubernetes ServiceAccount がアクセスできるすべてのバケットをマウントできます。詳細については、Cloud Storage FUSE ドキュメントの動的マウントをご覧ください。

   次のマニフェストの例は、これらの必須設定を示しています。

   • spec.csi.driver: CSI ドライバ名として gcsfuse.csi.storage.gke.io を使用します。

   必要に応じて、次の変数を調整できます。

   • spec.mountOptions: マウント オプションを Cloud Storage FUSE に渡します。フラグはスペースなしのカンマ区切りの 1 つの文字列で指定します。
   • spec.csi.volumeAttributes: ボリューム属性を Cloud Storage FUSE に渡します。

   Pod（ファイル キャッシュ保存）

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class 
     mountOptions:
       - implicit-dirs
       - file-cache:max-size-mb:-1
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE 
   

   次の値を置き換えます。

   • NAMESPACE: Pod をデプロイする Kubernetes Namespace。
   • BUCKET_NAME: Cloud Storage バケットへのアクセスを構成するときに指定した Cloud Storage バケット名。アンダースコア（_）を指定すると、Kubernetes ServiceAccount がアクセスできるすべてのバケットをマウントできます。詳細については、Cloud Storage FUSE ドキュメントの動的マウントをご覧ください。

   Pod（並列ダウンロード）

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class 
     mountOptions:
       - implicit-dirs
       - file-cache:enable-parallel-downloads:true
       - file-cache:max-size-mb:-1
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE 
   

   次の値を置き換えます。

   • NAMESPACE: Pod をデプロイする Kubernetes Namespace。
   • BUCKET_NAME: Cloud Storage バケットへのアクセスを構成するときに指定した Cloud Storage バケット名。アンダースコア（_）を指定すると、Kubernetes ServiceAccount がアクセスできるすべてのバケットをマウントできます。詳細については、Cloud Storage FUSE ドキュメントの動的マウントをご覧ください。

2. マニフェストをクラスタに適用します。

   kubectl apply -f PV_FILE_PATH
   

   PV_FILE_PATH は、YAML ファイルのパスに置き換えます。

PersistentVolumeClaim を作成する

1. 次の仕様で PersistentVolumeClaim マニフェストを作成します。

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: gcs-fuse-csi-static-pvc
     namespace: NAMESPACE
   spec:
     accessModes:
     - ReadWriteMany
     resources:
       requests:
         storage: 5Gi
     storageClassName: example-storage-class
   

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

   PersistentVolume を PersistentVolumeClaim にバインドするには、次の構成設定を確認します。

   • PersistentVolume マニフェストと PersistentVolumeClaim マニフェストの spec.storageClassName フィールドは一致している必要があります。storageClassName は、既存の StorageClass オブジェクトを参照する必要はありません。要求をボリュームにバインドするには、任意の名前を使用できますが、空にすることはできません。
   • PersistentVolume マニフェストと PersistentVolumeClaim マニフェストの spec.accessModes フィールドは一致している必要があります。
   • PersistentVolume マニフェストの spec.capacity.storage フィールドは、PersistentVolumeClaim マニフェストの spec.resources.requests.storage と一致する必要があります。Cloud Storage バケットにはサイズ制限がないため、任意の数を容量として設定できますが、空にすることはできません。

2. マニフェストをクラスタに適用します。

   kubectl apply -f PVC_FILE_PATH
   

   PVC_FILE_PATH は、YAML ファイルのパスに置き換えます。

Pod でボリュームを使用する

1. 次の仕様で Pod マニフェストを作成します。

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-example-static-pvc  
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
   spec:
     containers:
     - image: busybox
       name: busybox
       command: ["sleep"]
       args: ["infinity"]
       volumeMounts:
       - name: gcs-fuse-csi-static
         mountPath: /data
         readOnly: true
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-static
       persistentVolumeClaim:
         claimName: gcs-fuse-csi-static-pvc
         readOnly: true  
   

   次の値を置き換えます。

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

   次のマニフェストの例は、これらの必須設定を示しています。

   • metadata.annotations: アノテーション gke-gcsfuse/volumes: "true" は必須です。オプションのアノテーションについては、サイドカー コンテナを構成するをご覧ください。

   必要に応じて、次の変数を調整できます。

   • spec.containers[n].volumeMonts[n].readOnly: 特定のボリューム マウントのみが読み取り専用の場合は、true を指定します。
   • spec.volumes[n].persistentVolumeClaim.readOnly: すべてのボリューム マウントが読み取り専用の場合は、true を指定します。

2. マニフェストをクラスタに適用します。

   kubectl apply -f POD_FILE_PATH
   

   POD_FILE_PATH は、YAML ファイルのパスに置き換えます。

（省略可）同じ Cloud Storage バケットを異なる Persistent Volume でマウントする {:#mount-same-bucket-different-pv}。GKE バージョン 1.33.0-gke.1932000 以降で使用可能

複数の異なる永続ボリュームを使用して同じ Cloud Storage バケットをマウントするには、永続ボリュームごとに一意の volumeHandle を使用する必要があります。PersistentVolume オブジェクトの volumeHandle フィールドには、BUCKET_NAME:UNIQUE_SUFFIX 形式を使用します。BUCKET_NAME はバケットの名前に置き換え、UNIQUE_SUFFIX は任意の固有の識別子に置き換えます。例: myBucket:xyz123。

ユースケースの例としては、同じ Cloud Storage バケットを同じノードに複数回マウントし、それぞれに異なるマウント オプションのセットを指定することが考えられます。

問題のトラブルシューティング

Cloud Storage FUSE の問題のトラブルシューティングを行う場合は、log-severity フラグを TRACE に設定します。このフラグは、Deployment YAML 内のドライバのコンテナ仕様の args セクションで設定します。これにより、gcsfuseLoggingSeverity ボリューム属性が自動的に trace に設定されます。

その他のトラブルシューティングのヒントについては、GitHub プロジェクトのドキュメントのトラブルシューティング ガイドをご覧ください。

次のステップ

• Cloud Storage FUSE CSI ドライバのパフォーマンスを最適化する方法について学習する。
• GitHub で CSI ドライバの使用に関する追加のサンプルを確認する。
• Cloud Storage Fuse の詳細を確認する。