Cloud Storage FUSE CSI ドライバを使用して Cloud Storage バケットにアクセスする

Autopilot Standard

---

Filesystem in Userspace（FUSE）は、ファイル システムを Linux カーネルにエクスポートするために使用されるインターフェースです。Cloud Storage FUSE を使用すると、Cloud Storage バケットをファイル システムとしてマウントできます。これにより、アプリケーションは、クラウド固有の API を使用せずに、一般的なファイル IO オペレーション（オープン、読み取り、書き込みなど）を使用してバケット内のオブジェクトにアクセスできます。

Cloud Storage FUSE の CSI ドライバを使用すると、Kubernetes API を使用して既存の Cloud Storage バケットをボリュームとして使用できます。アプリケーションでは、Cloud Storage FUSE ファイル システム セマンティクスを使用して、オブジェクトのアップロードとダウンロードを行うことができます。Cloud Storage FUSE の CSI ドライバは、オープンソースの Google Cloud Storage FUSE の CSI ドライバを利用したフルマネージドのエクスペリエンスを提供します。

ドライバは、Cloud Storage を使用するボリュームを構成するために、次の方法をネイティブにサポートしています。

• CSI エフェメラル ボリューム: Pod 仕様に沿って Cloud Storage バケットを指定します。このボリューム タイプの詳細については、オープンソースの Kubernetes ドキュメントの CSI エフェメラル ボリュームの概要をご覧ください。

• 静的プロビジョニング: Cloud Storage バケットを参照する PersistentVolume リソースを作成します。これにより、Pod はこの PersistentVolume にバインドされた PersistentVolumeClaim を参照できます。このワークフローの詳細については、Storage で PersistentVolume を使用するように Pod を構成するをご覧ください。

Cloud Storage FUSE CSI ドライバとファイル キャッシュを併用することで、Cloud Storage バケットの小さなファイルを扱うアプリケーションの読み取りパフォーマンスを改善できます。Cloud Storage FUSE ファイル キャッシュ機能は、クライアント ベースの読み取りキャッシュで、これにより、選択したキャッシュ ストレージから繰り返し行うファイルの読み取りを、より短時間で行えるようにします。読み取りキャッシュは、ローカル SSD や Persistent Disk ベースのストレージなどのさまざまなストレージ オプションから、価格とパフォーマンスのニーズに基づいて選択できます。Cloud Storage FUSE CSI ドライバでファイル キャッシュを有効にするには、オプトインする必要があります。キャッシュのベスト プラクティスの詳細については、Cloud Storage FUSE のパフォーマンスとベスト プラクティスをご覧ください。

利点

• クラスタの Cloud Storage FUSE の CSI ドライバにより、ドライバの自動デプロイと管理が有効になります。ドライバは、Standard と Autopilot の両方のクラスタで機能します。
• Cloud Storage FUSE の CSI ドライバには、FUSE のクライアントで通常必要となる特権アクセスは必要ありません。これにより、セキュリティ対策が改善されます。
• CSI エフェメラル ボリュームのサポートにより、PersistentVolumeClaim オブジェクトと PersistentVolume オブジェクトが不要になり、ボリュームの構成と管理が簡素化されます。
• Cloud Storage FUSE の CSI ドライバは、ReadWriteMany、ReadOnlyMany、ReadWriteOnce のアクセスモードをサポートしています。
• GKE 用 Workload Identity 連携を使用すると、Pod が Cloud Storage オブジェクトにアクセスする方法を詳細に制御しながら、認証を管理できます。
• Ray、PyTorch、Spark、TensorFlow などのフレームワークを使用して、ML トレーニングを実行し、ワークロードを提供している場合、Cloud Storage FUSE CSI ドライバによるポータビリティとシンプルさにより、追加のコード変更をすることなく、ワークロードを GKE クラスタで直接実行できます。
• ファイル キャッシュを有効にして Cloud Storage オブジェクトを読み取ると、読み取りパフォーマンスを向上させることができます。ファイル キャッシュの利点については、Cloud Storage FUSE のドキュメントをご覧ください。
• Cloud Storage FUSE ボリュームを init コンテナで使用できます。

始める前に

作業を始める前に、次のことを確認してください。

• Google Kubernetes Engine API を有効にします。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化します。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得します。
  注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。

• Cloud Storage バケットを作成します。パフォーマンスを改善するには、Location type フィールドを Region に設定し、GKE クラスタが実行されているリージョンを選択します。

制限事項

• Cloud Storage FUSE ファイル システムでは、POSIX ファイル システムと比較して、パフォーマンス、可用性、アクセス承認、セマンティクスが異なります。
• Cloud Storage FUSE の CSI ドライバは、GKE Sandbox ではサポートされていません。
• Cloud Storage FUSE の CSI ドライバは、ボリューム スナップショット、ボリュームのクローン作成、ボリュームの拡張をサポートしていません。
• Cloud Storage FUSE の CSI ドライバの GitHub プロジェクトで既知の問題をご覧ください。
• Cloud Storage FUSE の CSI ドライバの GitHub プロジェクトで未解決の問題をご覧ください。現在、問題の優先度を判断しており、今後のアップデートで解決する予定です。

要件

Cloud Storage FUSE の CSI ドライバを使用するには、クラスタが次の要件を満たしている必要があります。

• GKE バージョン 1.24 以降を実行している Linux クラスタを使用する。
• GKE 用 Workload Identity 連携が有効になっている。
• ノードプールで GKE メタデータ サーバーが有効になっている。
• Google Cloud CLI の最新バージョンがインストールされていることを確認します。
• サイドカー コンテナ機能の限定公開イメージ、カスタム書き込みバッファ ボリューム機能を使用する、またはサイドカー コンテナのリソース リクエストを構成するには、クラスタで GKE バージョン 1.25.16-gke.1360000、1.26.13-gke.1052000、1.27.10-gke.1055000、1.28.6-gke.1369000、1.29.1-gke.1575000、または後続のバージョンが使用されていることを確認してください。
• ファイル キャッシュ機能やボリューム属性を使用するには、クラスタで GKE バージョン 1.29.3-gke.1093000 以降が使用されていることを確認してください。
• init コンテナで Cloud Storage FUSE ボリュームを使用するには、クラスタで GKE バージョン 1.29.3-gke.1093000 以降が使用され、クラスタ内のすべてのノードで GKE バージョン 1.29 以降が使用されていることを確認してください。

Cloud Storage FUSE の CSI ドライバを有効にする

注: Cloud Storage FUSE の CSI ドライバは、バージョン 1.24 以降の Autopilot クラスタではデフォルトで有効になっています。この機能を有効にするには、Autopilot クラスタをバージョン 1.24 以降にアップグレードします。クラスタで Cloud Storage FUSE の CSI ドライバが有効になっている場合は、GKE 用 GKE Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成するに進みます。

Cloud Storage FUSE の CSI ドライバが有効な Standard クラスタを作成するには、gcloud CLI を使用します。

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

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

• CLUSTER_NAME: クラスタの名前。
• VERSION: GKE のバージョン番号。 1.24 以降を選択する必要があります。
• LOCATION: クラスタの Compute Engine のロケーション。
• PROJECT_ID: プロジェクト ID。

既存の Standard クラスタでドライバを有効にするには、gcloud container clusters update コマンドを使用します。

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

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

• CLUSTER_NAME: クラスタの名前。
• LOCATION: クラスタの Compute Engine のロケーション。

Cloud Storage FUSE CSI ドライバを有効にした後は、ドライバとプロビジョナーの名前（gcsfuse.csi.storage.gke.io）を指定して Kubernetes ボリュームでドライバを使用できます。

GKE 用 Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成する

GKE 用の Workload Identity 連携を使用して、GKE クラスタから Cloud Storage バケットにアクセスできるようにするには、次の操作を行います。詳細については、GKE 用 Workload Identity 連携を使用するようにアプリケーションを構成するをご覧ください。

1. クラスタの認証情報を取得します。

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=LOCATION
   

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

   • CLUSTER_NAME: GKE 用 Workload Identity 連携が有効になっているクラスタの名前。
   • LOCATION: クラスタの Compute Engine のロケーション。

2. Kubernetes ServiceAccount に使用する Namespace を作成します。default Namespace を使用することも、既存の Namespace を使用することもできます。

   kubectl create namespace NAMESPACE
   

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

   • NAMESPACE: Kubernetes ServiceAccount の Kubernetes Namespace の名前。
   注: ワークロードは同じ Namespace で実行される必要があります。

3. アプリケーションで使用する Kubernetes ServiceAccount を作成します。また、default Kubernetes ServiceAccount を含む任意の Namespace で既存の Kubernetes ServiceAccount を使用することもできます。

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

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

   • KSA_NAME: 新しい Kubernetes ServiceAccount の名前。
   • NAMESPACE: Kubernetes ServiceAccount の Kubernetes Namespace の名前。

4. Cloud Storage の IAM ロールのいずれかを Kubernetes ServiceAccount に付与します。

   次のコマンドを使用して、特定の Cloud Storage バケットにアクセスするためだけのロールを Kubernetes ServiceAccount に付与できます。

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
       --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
       --role "ROLE_NAME"
   

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

   • BUCKET_NAME: Cloud Storage バケット名。
   • PROJECT_NUMBER: GKE クラスタの数値のプロジェクト番号。プロジェクト番号を確認するには、プロジェクトの識別をご覧ください。
   • PROJECT_ID: GKE クラスタのプロジェクト ID。
   • NAMESPACE: Kubernetes ServiceAccount の Kubernetes Namespace の名前。
   • KSA_NAME: 新しい Kubernetes ServiceAccount の名前。
   • ROLE_NAME: Kubernetes ServiceAccount に割り当てる IAM ロール。
     • 読み取り専用ワークロードの場合は、ストレージ オブジェクト閲覧者ロール（roles/storage.objectViewer）を使用します。
     • 読み取り / 書き込みワークロードの場合は、Storage Object ユーザーロールを使用します（roles/storage.objectUser）。

   必要に応じて、次のコマンドを使用して Kubernetes ServiceAccount にロールを付与し、プロジェクト内のすべての Cloud Storage バケットにアクセスできるようにします。

   gcloud projects add-iam-policy-binding GCS_PROJECT \
       --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
       --role "ROLE_NAME"
   

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

   • GCS_PROJECT: Cloud Storage バケットのプロジェクト ID。
   • PROJECT_NUMBER: GKE クラスタの数値のプロジェクト番号。プロジェクト番号を確認するには、プロジェクトの識別をご覧ください。
   • PROJECT_ID: GKE クラスタのプロジェクト ID。
   • NAMESPACE: Kubernetes ServiceAccount の Kubernetes Namespace の名前。
   • KSA_NAME: 新しい Kubernetes ServiceAccount の名前。
   • ROLE_NAME: Kubernetes ServiceAccount に割り当てる IAM ロール。
     • 読み取り専用ワークロードの場合は、ストレージ オブジェクト閲覧者ロール（roles/storage.objectViewer）を使用します。
     • 読み取り / 書き込みワークロードの場合は、Storage Object ユーザーロールを使用します（roles/storage.objectUser）。
   注: Cloud Storage バケットと GKE クラスタは、異なるプロジェクトにも同じプロジェクトにも配置できます。

Cloud Storage FUSE バケットをマウントする準備をする

このセクションでは、クラスタに Cloud Storage FUSE バケットをマウントするための準備を行う方法について説明します。

Pod アノテーションを指定する

CSI ドライバは、Pod アノテーションを使用して、Cloud Storage を利用するボリュームを Pod が使用しているかどうかを判別します。ドライバが必要なアノテーションを検出すると、gke-gcsfuse-sidecar というサイドカー コンテナをワークロード Pod に追加します。Cloud Storage FUSE インスタンスは、サイドカー コンテナ内で実行され、ワークロードの Cloud Storage バケットをマウントします。

CSI ドライバが Cloud Storage バケットをマウントできるようにするには、Pod 仕様の metadata フィールドにアノテーション gke-gcsfuse/volumes: "true" を指定します。Cloud Storage でサポートされるボリュームを他の Kubernetes ワークロード タイプ（Job や Deployment や StatefulSet など）で使用する場合は、アノテーションを spec.template.metadata.annotations フィールドに構成します。

サイドカー コンテナのリソースを構成する

デフォルトでは、サイドカー コンテナは次のリソース リクエストで構成され、リソースの上限は設定されていません。

• 250m CPU
• 256 MiB のメモリ
• 5 GiB のエフェメラル ストレージ

これらの値を上書きするには、必要に応じて次の例に示すようにアノテーション gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] を指定します。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

注: Autopilot によって、サイドカー コンテナのリソース構成が上書きされる可能性があります。詳細については、Autopilot のリソース リクエストをご覧ください。

割り当てるリソースの量を決定する際は、次の点を考慮してください。

• リソース リクエストまたはリソース上限のアノテーションのいずれか一方のみを設定した場合、GKE はリソース リクエストとリソース上限に同じ値を適用します。
• ワークロード Pod が複数の Cloud Storage ボリュームを使用する場合、サイドカー コンテナ リソースは複数の Cloud Storage FUSE インスタンスによって共有されます。これに該当する場合は、複数の Cloud Storage ボリュームに対するリソース割り当てを増やすことを検討してください。
• ワークロードでより高いスループットが必要な場合は、サイドカー コンテナにより多くの CPU を割り当てます。CPU が不足すると、Cloud Storage FUSE スロットリングが発生します。
• ワークロードで大量のファイルを処理する必要があり、Cloud Storage FUSE のメタデータ キャッシュが有効になっている場合は、サイドカー コンテナのメモリ割り当てを増やします。メタデータをキャッシュに保存する際の Cloud Storage FUSE のメモリ消費量は、ファイル数に比例しますが、ファイルサイズには比例しません。メモリが不足すると、Cloud Storage FUSE のメモリ不足エラーが発生し、ワークロード アプリケーションがクラッシュします。
• ファイル キャッシュの場合、Cloud Storage FUSE はデフォルトでローカルの一時ディレクトリにファイルをキャッシュに保存します。ファイル キャッシュに必要なワークロードの空き容量を見積もり、それに応じてエフェメラル ストレージの上限を引き上げます。詳細については、ボリューム属性をご覧ください。
• 書き込みオペレーションの場合、ファイルが Cloud Storage バケットにアップロードされる前に、デフォルトで Cloud Storage FUSE がローカルの一時ディレクトリにあるファイルをステージングします。大きなファイルを書き込むときにワークロードがステージングに必要な空き容量を見積もり、それに応じてエフェメラル ストレージの上限を引き上げます。詳細については、Cloud Storage FUSE GitHub ドキュメントの読み取り / 書き込みのセマンティクスをご覧ください。
• 値 "0" を使用すると、Standard クラスタに対するリソース上限またはリクエストの設定を解除できます。たとえば、アノテーション gke-gcsfuse/memory-limit: "0" により、サイドカー コンテナのメモリ上限はデフォルトのメモリ リクエストで空になります。これは、ワークロードに対して Cloud Storage FUSE で必要になるリソースの量を特定できず、ノード上の使用可能なすべてのリソースを Cloud Storage FUSE が消費できるようにする必要がある場合に有効です。ワークロードの指標に基づいて Cloud Storage FUSE のリソース要件を計算した後、適切な上限を設定できます。

注: 値 "0" を使用して、サイドカー コンテナのリソース上限と Autopilot クラスタのリクエストの設定を解除することはできません。

注: 値 "0" を使用してサイドカー コンテナ リソースの上限とリクエストの設定を解除すると、GKE は Pod Quality of Service（QoS）クラスを BestEffort に変更します。

注:メインのワークロード コンテナにエフェメラル ストレージの上限がない場合、Pod アノテーション gke-gcsfuse/ephemeral-storage-limit により Pod レベルでエフェメラル ストレージの上限が設定されますが、CPU とメモリの上限はサイドカー コンテナでのみ有効になります。エフェメラル ストレージを大量に消費する場合は、メイン ワークロード コンテナにエフェメラル ストレージの上限を構成することを検討してください。詳細については、ローカル エフェメラル ストレージのリクエストと制限の設定をご覧ください。

サイドカー コンテナの非公開イメージを構成する

このセクションでは、限定公開コンテナ レジストリにホストされているサイドカー コンテナ イメージの使用方法について説明します。このシナリオは、セキュリティ上の目的で限定公開クラスタを使用する必要がある場合や、クラスタで公共のインターネットへのアクセスが制限されている場合に適用されます。限定公開のサイドカー コンテナ イメージを構成して使用するには、次の操作を行います。

1. 互換性のある公開サイドカー コンテナ イメージについては、こちらのページをご覧ください。

2. ローカル環境に pull して限定公開コンテナ レジストリに push します。

3. マニフェストで、image フィールドのみを含む gke-gcsfuse-sidecar という名前のコンテナを指定します。GKE は、指定されたサイドカー コンテナ イメージを使用して、サイドカー コンテナ インジェクションを準備します。以下に例を示します。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

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

• PRIVATE_REGISTRY: 限定公開のコンテナ レジストリ。
• PRIVATE_IMAGE_TAG: 限定公開のサイドカー コンテナ イメージのタグ。

サイドカー コンテナのカスタム書き込みバッファ ボリュームを構成する

このセクションでは、Cloud Storage FUSE 書き込みバッファリング用のカスタム バッファ ボリュームを構成する方法について説明します。このシナリオは、Cloud Storage FUSE のデフォルトの emptyDir ボリュームを置き換えて、書き込みオペレーションでファイルをステージングする必要がある場合に適用できます。GKE でサポートされている任意のタイプのストレージ（PersistentVolumeClaim など）を指定できます。GKE は、指定されたボリュームをファイルの書き込みバッファに使用します。これは、Autopilot クラスタで 10 GiB を超えるファイルを書き込む必要がある場合に有効です。カスタム バッファ ボリュームを使用するには、ゼロ以外の fsGroup を指定する必要があります。次の例は、バッファ ボリュームとして事前定義済みの PVC を使用する方法を示しています。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

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

• FS_GROUP: fsGroup ID。
• BUFFER_VOLUME_PVC: 事前定義された PVC 名。

サイドカー コンテナのカスタム読み取りキャッシュ ボリュームを構成する

このセクションでは、Cloud Storage FUSE 読み取りキャッシュ用にカスタム キャッシュ ボリュームを構成する方法について説明します。このシナリオは、Cloud Storage FUSE のデフォルトの emptyDir ボリュームを置き換えて、読み取りオペレーションでファイルをキャッシュに保存する必要がある場合に適用できます。GKE でサポートされている任意のタイプのストレージ（PersistentVolumeClaim など）を指定できます。GKE は、指定されたボリュームをファイル キャッシュに使用します。これは、Autopilot クラスタで 10 GiB を超えるファイルをキャッシュに保存する必要がある場合に有効です。カスタム キャッシュ ボリュームを使用するには、ゼロ以外の fsGroup を指定する必要があります。次の例では、キャッシュ ボリュームとして事前定義済みの PVC を使用する方法を示します。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

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

• FS_GROUP: fsGroup ID。
• CACHE_VOLUME_PVC: 事前定義された PVC 名。

ボリュームを CSI エフェメラル ボリュームとしてプロビジョニングする

Cloud Storage バケットを基盤とする CSI エフェメラル ボリュームは、Pod のライフサイクルに関連付けられます。このプロビジョニング方法では、Pod の終了後に、Cloud Storage バケットに関連付けられた PersistentVolume オブジェクトと PersistentVolumeClaim オブジェクトを維持する必要はありません。

注: CSI エフェメラル ボリュームを使用する場合も、使用する前にバケットを作成し、必要に応じてバケットを削除する必要があります。

注: gke-gcsfuse-sidecar と gke-gcsfuse-tmp という名前は使用しないでください。これらは、CSI ドライバが作成するオブジェクト用に予約されている名前です。

Pod で CSI エフェメラル ストレージ ボリュームを使用する

1. 次の YAML マニフェストを保存します。

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-example-ephemeral
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
   spec:
     terminationGracePeriodSeconds: 60
     containers:
     - image: busybox
       name: busybox
       command: ["sleep"]
       args: ["infinity"]
       volumeMounts:
       - name: gcs-fuse-csi-ephemeral
         mountPath: /data
         readOnly: true
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-ephemeral
       csi:
         driver: gcsfuse.csi.storage.gke.io
         readOnly: true
         volumeAttributes:
           bucketName: BUCKET_NAME
           mountOptions: "implicit-dirs"
           gcsfuseLoggingSeverity: warning
   

   上記の例は、Pod マニフェストで Cloud Storage バケットをインラインで指定する方法を示しています。この例には次のフィールドがあります。

   • metadata.annotations: アノテーション gke-gcsfuse/volumes: "true" は必須です。オプションのアノテーションについては、サイドカー コンテナのリソースを構成するをご覧ください。
   • spec.terminationGracePeriodSeconds: 省略可。デフォルトの設定値は 30 です。サイズの大きいファイルを Cloud Storage バケットに書き込む必要がある場合は、この値を引き上げて、Cloud Storage FUSE がアプリケーションの終了後にデータをフラッシュするのに十分な時間を確保します。詳細については、Kubernetes のベスト プラクティス: 猶予期間による終了をご覧ください。
   • spec.serviceAccountName: GKE 用 Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成するの手順と同じ Kubernetes ServiceAccount を使用します。
   • spec.volumes[n].csi.driver: CSI ドライバ名として gcsfuse.csi.storage.gke.io を使用します。
   • spec.volumes[n].csi.volumeAttributes.bucketName: Cloud Storage FUSE のバケット名を指定します。アンダースコア（_）を指定すると、Kubernetes ServiceAccount がアクセスできるすべてのバケットをマウントできます。詳細については、Cloud Storage FUSE ドキュメントの動的マウントをご覧ください。
   • spec.volumes[n].csi.volumeAttributes.mountOptions: 省略可。マウント オプションを Cloud Storage FUSE に渡します。フラグはスペースなしのカンマ区切りの 1 つの文字列で指定します。
   • spec.volumes[n].csi.volumeAttributes: 省略可。他のボリューム属性を Cloud Storage FUSE に渡します。
   • spec.volumes[n].csi.readOnly: 省略可。すべてのボリューム マウントが読み取り専用の場合は、true を指定します。
   • spec.containers[n].volumeMounts[m].readOnly: 省略可。特定のボリューム マウントのみが読み取り専用の場合は、true を指定します。

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

   kubectl apply -f FILE_PATH
   

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

ジョブ ワークロードで CSI エフェメラル ストレージ ボリュームを使用する

1. 次の YAML マニフェストを保存します。

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: gcs-fuse-csi-job-example
     namespace: NAMESPACE
   spec:
     template:
       metadata:
         annotations:
           gke-gcsfuse/volumes: "true"
       spec:
         serviceAccountName: KSA_NAME
         containers:
         - name: writer
           image: busybox
           command:
             - "/bin/sh"
             - "-c"
             - touch /data/test && echo $(date) >> /data/test && sleep 10
           volumeMounts:
           - name: gcs-fuse-csi-ephemeral
             mountPath: /data
         - name: reader
           image: busybox
           command:
             - "/bin/sh"
             - "-c"
             - sleep 10 && cat /data/test
           volumeMounts:
           - name: gcs-fuse-csi-ephemeral
             mountPath: /data
             readOnly: true
         volumes:
         - name: gcs-fuse-csi-ephemeral
           csi:
             driver: gcsfuse.csi.storage.gke.io
             volumeAttributes:
               bucketName: BUCKET_NAME
         restartPolicy: Never
     backoffLimit: 1
   

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

   • NAMESPACE: ワークロードの Namespace。
   • KSA_NAME: GKE 用 Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成するの手順にある Kubernetes ServiceAccount 名。
   • BUCKET_NAME: Cloud Storage バケット名。

   マニフェストは、CSI エフェメラル ボリュームを介して Cloud Storage FUSE バケットを使用する Job をデプロイします。

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

   kubectl apply -f FILE_PATH
   

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

Job ワークロードで CSI ドライバを使用している場合、または Pod RestartPolicy が Never の場合、サイドカー コンテナは他のすべてのワークロード コンテナが終了した後に自動的に終了します。

その他の例については、GitHub プロジェクトに関するドキュメントのサンプル アプリケーションをご覧ください。

静的プロビジョニングを使用してボリュームをプロビジョニングする

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

注: gke-gcsfuse-sidecar と gke-gcsfuse-tmp の名前を使用しないようにします。これらは、CSI ドライバが作成するオブジェクトの予約済み名です。

PersistentVolume を作成する

1. 次の YAML マニフェストを保存します。

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

   マニフェストの例は、Cloud Storage バケットに PersistentVolume を定義する方法を示しています。この例には次のフィールドがあります。

   • spec.claimRef.namespace: PersistentVolumeClaim Namespace を指定します。
   • spec.claimRef.name: PersistentVolumeClaim の名前を指定します。
   • spec.csi.driver: CSI ドライバ名として gcsfuse.csi.storage.gke.io を使用します。
   • spec.csi.volumeHandle: Cloud Storage バケット名を指定します。アンダースコア（_）を渡すことで、Kubernetes ServiceAccount がアクセスできるように構成しているすべてのバケットをマウントできます。詳細については、Cloud Storage FUSE ドキュメントの動的マウントをご覧ください。
   • spec.mountOptions: 省略可。マウント オプションを Cloud Storage FUSE に渡します。
   • spec.csi.volumeAttributes: 省略可。ボリューム属性を Cloud Storage FUSE に渡します。

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

   kubectl apply -f FILE_PATH
   

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

PersistentVolumeClaim を作成する

1. 次の YAML マニフェストを保存します。

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

   マニフェストの例は、PersistentVolumeClaim を定義して PersistentVolume をバインドする方法を示しています。この例には次のフィールドがあります。

   • metadata.namespace: ワークロードの Namespace と一貫している必要がある PersistentVolumeClaim Namespace を指定します。
   • spec.volumeName: PersistentVolume の名前を指定します。

   PersistentVolume を PersistentVolumeClaim にバインドするには、次のガイドラインに沿ってください。

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

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

   kubectl apply -f FILE_PATH
   

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

PersistentVolumeClaim のボリュームを使用する

1. 次の YAML マニフェストを保存します。

   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
   

   この例では、PersistentVolumeClaim を介して Cloud Storage FUSE バケットを使用する Pod を定義する方法を示しています。この例には次のフィールドがあります。

   • metadata.annotations: アノテーション gke-gcsfuse/volumes: "true" は必須です。オプションのアノテーションについては、サイドカー コンテナのリソースを構成するをご覧ください。
   • spec.serviceAccountName: GKE 用 Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成するの手順と同じ Kubernetes ServiceAccount を使用します。
   • spec.containers[n].volumeMounts[m].readOnly: 省略可。特定のボリューム マウントのみが読み取り専用の場合は、true を指定します。
   • spec.volumes[n].persistentVolumeClaim.readOnly: 省略可。すべてのボリューム マウントが読み取り専用の場合は、true を指定します。

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

   kubectl apply -f FILE_PATH
   

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

その他の例については、GitHub プロジェクトに関するドキュメントのサンプル アプリケーションをご覧ください。

ファイル キャッシュを有効にしてボリュームを使用する

デフォルトでは、GKE におけるファイル キャッシュ機能は無効になっています。ファイル キャッシュを有効にして制御するには、ボリューム属性 fileCacheCapacity を使用します。

GKE は、ノード VM ブートディスクによってサポートされる Cloud Storage FUSE のファイル キャッシュに emptyDir ボリュームを使用します。ノードでローカル SSD を有効にすると、GKE はローカル SSD を使用して emptyDir ボリュームをサポートします。

読み取りオペレーションにおけるファイル キャッシュのデフォルトの emptyDir ボリュームは、サイドカー コンテナのカスタム読み取りキャッシュ ボリュームを構成することで置き換えできます。ローカル SSD をサポートする CPU VM ファミリーと GPU VM ファミリーでは、ローカル SSD ストレージの使用をおすすめします。TPU ファミリーや Autopilot の場合は、バランス永続ディスクか SSD 永続ディスクの使用をおすすめします。

注: ファイル キャッシュにデフォルトの emptyDir ボリュームを使用する場合、Pod アノテーション gke-gcsfuse/ephemeral-storage-limit の値は fileCacheCapacity ボリューム属性よりも大きくする必要があります。カスタム キャッシュ ボリュームを使用する場合、基盤となるボリューム サイズは fileCacheCapacity ボリューム属性よりも大きくする必要があります。

ファイル キャッシュを有効にして CSI エフェメラル ストレージ ボリュームを使用する

ファイル キャッシュがある CSI エフェメラル ボリュームを介して Cloud Storage FUSE バケットを使用する Pod をデプロイするには、以下の手順に沿って操作します。

1. ローカル SSD を基盤とするエフェメラル ストレージを備えたクラスタまたはノードプールを作成します。

   GKE のドキュメントに従って、ローカル SSD を基盤とするエフェメラル ストレージを備えたクラスタまたはノードプールを作成します。

2. 次の YAML マニフェストを保存します。

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-file-cache-example
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
       gke-gcsfuse/ephemeral-storage-limit: "50Gi"
   spec:
     nodeSelector:
       cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
     restartPolicy: Never
     initContainers:
     - name: data-loader
       image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
       resources:
         limits:
           cpu: 500m
           memory: 1Gi
         requests:
           cpu: 500m
           memory: 1Gi
       command:
         - "/bin/sh"
         - "-c"
         - |
           mkdir -p /test_files
           for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
           gsutil -m cp -r /test_files gs://BUCKET_NAME
     containers:
     - name: data-validator
       image: busybox
       resources:
         limits:
           cpu: 500m
           memory: 512Mi
         requests:
           cpu: 500m
           memory: 512Mi
       command:
         - "/bin/sh"
         - "-c"
         - |
           echo "first read with cache miss"
           time cat /data/test_files/file_* > /dev/null
   
           echo "second read from local cache"
           time cat /data/test_files/file_* > /dev/null
       volumeMounts:
       - name: gcs-fuse-csi-ephemeral
         mountPath: /data
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-ephemeral
       csi:
         driver: gcsfuse.csi.storage.gke.io
         volumeAttributes:
           bucketName: BUCKET_NAME
           mountOptions: "implicit-dirs"
           fileCacheCapacity: "10Gi"
   

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

   • NAMESPACE: ワークロードの Namespace。
   • KSA_NAME: GKE 用 Workload Identity 連携を使用して Cloud Storage バケットへのアクセスを構成するの手順で指定した Kubernetes ServiceAccount 名。
   • BUCKET_NAME: Cloud Storage バケット名。

   init コンテナ data-loader は、サイズが 64 KiB のファイルを 1,000 個作成して、Cloud Storage バケットにアップロードします。メインコンテナ data-validator は、バケット内のすべてのファイルを 2 回読み取り、それにかかった期間をログに記録します。

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

   kubectl apply -f FILE_PATH
   

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

4. ログ出力を表示するには、次のコマンドを実行します。

   kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator
   

   NAMESPACE は、ワークロードの名前空間に置き換えます。

   出力は次のようになります。

   first read with cache miss
   real    0m 54.68s
   ...
   second read from local cache
   real    0m 0.38s
   ...
   

   出力から、ローカル キャッシュを使用した 2 回目の読み取りが、キャッシュミスを使用した 1 回目の読み取りよりもはるかに高速であることがわかります。

Cloud Storage FUSE バケットのマウント方法を構成する

このセクションでは、Cloud Storage FUSE ボリュームを構成する方法について説明します。

マウント オプション

Cloud Storage FUSE CSI ドライバは、Cloud Storage バケットをローカル ファイル システムにどのようにマウントするかを構成するマウント オプションをサポートします。サポートされているマウント オプションの全一覧については、gcsfuse CLI のドキュメントをご覧ください。

マウントフラグは次の方法で指定できます。

• 静的プロビジョニングを使用する場合、PersistentVolume マニフェストの spec.mountOptions フィールド。
• CSI エフェメラル ボリュームを使用する場合、spec.volumes[n].csi.volumeAttributes.mountOptions フィールド。

ボリューム属性

Cloud Storage FUSE CSI ドライバでは、Cloud Storage FUSE 構成ファイルを直接指定できません。以下のボリューム属性を使用して、構成ファイル内の一部のフィールドを構成できます。値は構成ファイルのフィールドに変換されます。

• gcsfuseLoggingSeverity

  • 説明: Cloud Storage FUSE で生成するログの重大度が列挙型で表されます。すでに debug_fuse、debug_fs、または debug_gcs のマウント オプションを使用している場合、この新しい構成は自動的に trace に設定されます。このボリューム属性は、構成ファイルの logging:severity フィールドに変換されます。

  • 有効な値（重大度が低い順）:

    • trace
    • debug
    • info
    • warning
    • error

  • デフォルト値: info

• fileCacheCapacity

  • 説明: ファイル キャッシュで使用できる最大サイズ。ゼロ以外の値が指定された場合、このボリューム属性により、Cloud Storage FUSE でのファイル キャッシュが有効になります。このボリューム属性は、構成ファイルの file-cache:max-size-mb フィールドに変換されます。

  • 有効な値:

    • 数量値（例: 500Mi、10Gi）。
    • 「-1」: キャッシュ ボリュームの使用可能な容量全体を使用します。
    • 「0」: ファイルのキャッシュ保存は無効です。

  • デフォルト値: 「0」

• fileCacheForRangeRead

  • 説明: ゼロ以外のオフセットから最初の読み取りが行われたときに、オブジェクト全体を非同期的にダウンロードして Cloud Storage FUSE キャッシュ ディレクトリに保存するかどうかを示します。ランダム読み取りまたは部分読み取りを複数回行う場合は、この値を「true」に設定する必要があります。このボリューム属性は、構成ファイルの file-cache:cache-file-for-range-read フィールドに変換されます。

  • 有効な値:

    • 文字列形式のブール値（「true」、「false」）。

  • デフォルト値: 「false」

• metadataStatCacheCapacity

  • 説明: 統計情報キャッシュで使用できる最大サイズ。統計情報キャッシュは常にメモリ内に保持されます。stat-cache-capacity マウント オプションをすでに使用している場合、その値は引き続き有効で、この新しい構成に適切に変換されます。このボリューム属性は、構成ファイルの metadata-cache:stat-cache-max-size-mb フィールドに変換されます。

  • 有効な値:

    • 数量値（例: 500Mi、1Gi）。
    • 「-1」: 統計キャッシュが必要なだけメモリを使用できるようにします。
    • 「0」: 統計キャッシュは無効です。
    • ワークロードに最大 20,000 個のファイルが含まれる場合は、デフォルト値の 32Mi を使用します。ワークロードのファイルが 20,000 ファイルを超える場合は、6,000 ファイルを追加するごとにサイズを 10 MiB ずつ増やします（ファイルあたり平均約 1,500 バイト）。

  • デフォルト値: 32Mi

• metadataTypeCacheCapacity

  • 説明: タイプ キャッシュで使用できるディレクトリあたりの最大サイズ。タイプ キャッシュは常にメモリ内に保持されます。このボリューム属性は、構成ファイルの metadata-cache:type-cache-max-size-mb フィールドに変換されます。

  • 有効な値:

    • 数量値（例: 500Mi、1Gi）。
    • 「-1」: タイプ キャッシュが必要なだけメモリを使用できるようにします。
    • 「0」: タイプ キャッシュは無効です。
    • マウントするバケットの 1 つのディレクトリ内にあるファイルの最大数が 20,000 以下の場合は、デフォルト値の 4Mi を使用します。マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとにサイズを 1 MiB 増やします（ファイルあたり平均約 200 バイト）。

  • デフォルト値: 4Mi

• metadataCacheTtlSeconds

  • 説明: キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で指定します。stat-cache-ttl または type-cache-ttl マウント オプションをすでに使用している場合、その値は引き続き有効で、この新しい構成に適切に変換されます。このボリューム属性は、構成ファイルの metadata-cache:ttl-secs フィールドに変換されます。

  • 有効な値:

    • 文字列形式の整数値（例: 「600」）。
    • 「-1」: TTL の有効期限をバイパスし、キャッシュから利用可能な場合にファイルを配信します。
    • 「0」: 最新のファイルが読み取られるようにします。0 の値を使用すると、Get メタデータ呼び出しが行われ、キャッシュ内のファイルのオブジェクトの世代が Cloud Storage に保存されているものと一致するようにします。

  • デフォルト値:: 「60」

ボリューム属性は、次の方法で指定できます。

• 静的プロビジョニングを使用する場合、PersistentVolume マニフェストの spec.csi.volumeAttributes フィールド。
• CSI エフェメラル ボリュームを使用する場合、spec.volumes[n].csi.volumeAttributes フィールド。

考慮事項

マウントを構成する際は、次の点を考慮してください。

• 次のフラグは使用できません: app-name、temp-dir、foreground、log-file、log-format、key-file、token-url、reuse-token-from-url。
• Cloud Storage FUSE では、デフォルトで暗黙のディレクトリは表示されません。これらのディレクトリを表示するには、implicit-dirs マウントフラグを有効にします。詳細については、Cloud Storage FUSE の GitHub ドキュメントのファイルとディレクトリをご覧ください。
• Pod またはコンテナにセキュリティ コンテキストを使用する場合、またはコンテナ イメージが root 以外のユーザーまたはグループを使用する場合は、uid と gid のマウントフラグを設定する必要があります。ファイル システムの権限を設定するには、file-mode マウントフラグと dir-mode マウントフラグも使用する必要があります。Cloud Storage FUSE ファイル システムに対して chmod、chown、chgrp コマンドを実行することはできません。したがって、uid、gid、file-mode、dir-mode マウントフラグは、root 以外のユーザーまたはグループにアクセス権を付与するために必要です。
• バケット全体ではなくバケット内のディレクトリのみをマウントする場合は、only-dir=relative/path/to/the/bucket/root フラグを使用してディレクトリの相対パスを渡します。
• Cloud Storage FUSE のキャッシュ保存の動作を調整するには、ボリューム属性を構成します。詳細については、Cloud Storage FUSE のキャッシュ保存のドキュメントをご覧ください。
• コア数またはスレッド数が 100 を超える場合は、max-cons-per-host をこの値に変更します。
• Linux カーネルのマウント オプションを構成する必要がある場合は、o フラグを使用してオプションを渡すことができます。たとえば、マウントされたファイル システムでバイナリの直接実行を許可しない場合は、o=noexec フラグを設定します。 各オプションには、o=noexec,o=noatime などの個別のフラグが必要です。使用できるオプションは、exec、noexec、atime、noatime、sync、async、dirsync のみです。
• Cloud Storage FUSE の問題のトラブルシューティングを行う場合は、debug_fuse、debug_fs、debug_gcs の各フラグを設定します。3 つのオプションのいずれかを指定すると、gcsfuseLoggingSeverity ボリューム属性が自動的に trace に設定されます。
• Cloud Storage FUSE CSI ドライバで、Cloud Storage FUSE 構成ファイルの cache-dir フィールドを変更することはできません。ファイル キャッシュを有効または無効にするには、fileCacheCapacity ボリューム属性を使用します。ファイル キャッシュに対するデフォルトの emptyDir ボリュームを置き換えるには、サイドカー コンテナのカスタム キャッシュ ボリュームを構成します。

Cloud Storage FUSE の CSI ドライバを無効にする

Autopilot クラスタで Cloud Storage FUSE の CSI ドライバを無効にすることはできません。

既存の Standard クラスタで Cloud Storage FUSE の CSI ドライバを無効にするには、Google Cloud CLI を使用します。

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

CLUSTER_NAME は、使用するクラスタの名前に置き換えます。

トラブルシューティング

Cloud Storage FUSE の CSI ドライバの使用時に発生する問題のトラブルシューティングについては、GitHub プロジェクトのドキュメントのトラブルシューティング ガイドをご覧ください。

次のステップ

• GitHub で CSI ドライバの詳細を確認する。
• Cloud Storage Fuse の詳細を確認する。