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

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

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

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

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

始める前に

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

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 の名前空間に置き換えます。

    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

    次の値を置き換えます。

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

    • 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 バケットを異なる PersistentVolume でマウントする

GKE バージョン 1.33.0-gke.1932000 以降では、同じ Cloud Storage バケットを基盤とする複数の PersistentVolume を使用できます。各 PersistentVolume オブジェクトでは、BUCKET_NAME:UNIQUE_SUFFIX 形式で一意の volumeHandle を使用する必要があります。

ユースケースの例としては、異なるマウント オプションを持つ異なる PersistentVolume を同じ Pod にマウントし、各 PersistentVolume が同じ Cloud Storage バケットを参照することが考えられます。

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

Cloud Storage FUSE の CSI ドライバのトラブルシューティングの詳細については、GitHub プロジェクトのドキュメントのトラブルシューティング ガイドをご覧ください。

次のステップ