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 バケットの永続ボリュームの仕組み

静的プロビジョニングを使用して、基盤となるストレージ システムの詳細を含む 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"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
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 FUSE の問題のトラブルシューティングを行う場合は、log-severity フラグを TRACE に設定できます。このフラグは、Deployment YAML でドライバのコンテナ仕様の args セクションに設定します。これにより、gcsfuseLoggingSeverity ボリューム属性が自動的にトレース設定されます。

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

次のステップ