GKE 用に Cloud Storage FUSE CSI ドライバを設定する

Autopilot Standard

このドキュメントでは、Cloud Storage FUSE CSI ドライバを設定して、Google Kubernetes Engine（GKE）から Cloud Storage バケットにアクセスする方法について説明します。

Cloud Storage FUSE CSI ドライバを使用すると、GKE ワークロードは Cloud Storage バケットにローカル ファイル システムとしてアクセスできます。CSI ドライバは Cloud Storage を GKE と統合し、コンテナ化されたアプリケーションがバケットに保存されている大規模なデータセットとやり取りする方法を簡素化します。CSI ドライバは、GKE ストレージの標準インターフェースを提供します。このドキュメントでは、Cloud Storage FUSE CSI ドライバを使用して環境を準備し、GKE クラスタを Cloud Storage バケットに接続します。

このドキュメントは、GKE ワークロードをオブジェクト ストレージと統合するデベロッパー、管理者、ストレージ スペシャリストを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

Cloud Storage バケットを作成する

まだ作成していない場合は、Cloud Storage バケットを作成します。作成したバケットは、GKE クラスタのボリュームとしてマウントします。パフォーマンスを改善するには、[ロケーション タイプ] を [リージョン] に設定し、GKE クラスタと同じリージョンを選択します。

ヒント: Cloud Storage バケットと GKE クラスタは、異なる Google Cloud プロジェクトに配置しても、同じプロジェクトに配置してもかまいません。

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

GKE Autopilot クラスタと GKE Standard クラスタのどちらを使用しているかに応じて、次のいずれかの手順を行います。フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用することをおすすめします。ワークロードに最適なモードを選択する方法について、GKE の運用モードを選択するをご覧ください。

Autopilot

Autopilot クラスタを使用する場合、Cloud Storage FUSE の CSI ドライバは、デフォルトで有効になっています。Cloud Storage バケットへのアクセスを構成するに進んでください。

Standard

Standard クラスタで Cloud Storage FUSE CSI ドライバが有効になっている場合は、Cloud Storage バケットへのアクセスを構成するに進みます。

Cloud Storage FUSE の CSI ドライバは、Standard クラスタではデフォルトで有効になっていません。Cloud Storage FUSE の CSI ドライバが有効な Standard クラスタを作成するには、gcloud container clusters create コマンドを使用します。

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

クラスタで Cloud Storage FUSE CSI ドライバが有効になっていることを確認するには、次のコマンドを実行します。

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --format="value(addonsConfig.gcsFuseCsiDriverConfig.enabled)"

Cloud Storage バケットへのアクセスを構成する

Cloud Storage FUSE CSI ドライバは Workload Identity Federation for GKE を使用するため、GKE Pod が Cloud Storage に保存されているデータにアクセスする方法について、きめ細かい権限を設定できます。

GKE クラスタから Cloud Storage バケットにアクセスできるようにするには、Pod 仕様でマウントする Cloud Storage バケットについて、Workload Identity Federation for GKE を使用して認証します。

1. Workload Identity Federation for GKE が有効になっていない場合は、こちらの手順に沿って有効にします。既存のノードプールを使用する場合は、クラスタで Workload Identity Federation for GKE を有効にしてから、ノードプールで Workload Identity Federation for GKE を手動で有効にします。

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

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

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

   • CLUSTER_NAME: Workload Identity Federation for GKE が有効になっているクラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン。

3. Kubernetes サービス アカウントに使用する Namespace を作成します。default Namespace を使用することも、既存の Namespace を使用することもできます。

   kubectl create namespace NAMESPACE
   

   NAMESPACE は、Kubernetes ServiceAccount の Kubernetes Namespace の名前に置き換えます。

   重要: ワークロードは同じ Namespace で実行する必要があります。

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

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   KSA_NAME は、Kubernetes ServiceAccount の名前に置き換えます。

5. Cloud Storage の IAM ロールのいずれかを Kubernetes ServiceAccount に付与します。Kubernetes ServiceAccount に特定の Cloud Storage バケットへのアクセス権のみを付与する場合、またはプロジェクト内のすべてのバケットへのグローバル アクセス権を付与する場合に応じて、次のいずれかの手順を行います。

   特定のバケットへのアクセス

   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 オブジェクト ユーザーロールを使用します（roles/storage.objectUser）。

   グローバル バケット アクセス

   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 オブジェクト ユーザーロールを使用します（roles/storage.objectUser）。

ホスト ネットワークを使用する Pod のアクセスを構成する

1.33.3-gke.1226000 より前の GKE クラスタ バージョンでは、Workload Identity Federation for GKE の制限事項により、Cloud Storage FUSE CSI ドライバはホスト ネットワーク（hostNetwork: true）で実行されている Pod をサポートしていません。ただし、それ以降の GKE バージョンでは、Cloud Storage FUSE CSI ドライバを使用して Cloud Storage バケットをマウントするときに、hostNetwork が有効になっている Pod に対して安全な認証を構成できます。ホスト ネットワークのサポートは、Standard GKE クラスタでのみ使用できます。

GKE クラスタが次の要件を満たしていることを確認します。

• Standard GKE クラスタのコントロール プレーンとノードプールは、バージョン 1.33.3-gke.1226000 以降である必要があります。
• クラスタで Workload Identity を有効にします。
• hostNetwork 対応の Pod が Cloud Storage バケットにアクセスするために使用する Kubernetes サービス アカウントに対して、必要な IAM 権限を付与します。詳細については、Cloud Storage FUSE に対する認証を行うをご覧ください。

Pod または PersistentVolume の定義でボリューム属性 hostNetworkPodKSA: "true" を指定して、HostNetwork Pod が Cloud Storage ボリュームにアクセスできるようにします。具体的な構成は、Cloud Storage FUSE サイドカー コンテナの管理方法によって異なります。

マネージド サイドカー

このセクションの内容は、GKE が Cloud Storage FUSE サイドカー コンテナを Pod に自動的に挿入して管理する場合に適用されます。このオプションは、Cloud Storage FUSE CSI ドライバのデフォルトであり、推奨設定です。

エフェメラル ボリューム

次の Pod マニフェストは、HostNetwork Pod が Cloud Storage バケットにアクセスするようにエフェメラル ボリュームを構成します。

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"

永続ボリューム

次の PV マニフェストは、HostNetwork Pod が Cloud Storage バケットにアクセスするように PV を構成します。

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"

プライベート サイドカー

このセクションの内容は、Pod 内で Cloud Storage FUSE サイドカー コンテナを手動で管理する場合、またはカスタムのサイドカー イメージを使用する場合に適用されます。

使用するサイドカー イメージが、Cloud Storage FUSE CSI ドライバ バージョン v1.17.2 以降に基づいていることを確認してください。

エフェメラル ボリューム

次の Pod マニフェストは、HostNetwork Pod が Cloud Storage バケットにアクセスするようにエフェメラル ボリュームを構成します。

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"
        identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

identityProvider フィールドの各値を、次のように置き換えます。

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: クラスタのロケーション。
• CLUSTER_NAME: Standard GKE クラスタの名前。

永続ボリューム

次の PV マニフェストは、HostNetwork Pod が Cloud Storage バケットにアクセスするように PV を構成します。

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"
    identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

identityProvider フィールドの各値を、次のように置き換えます。

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: クラスタのロケーション。
• CLUSTER_NAME: Standard GKE クラスタの名前。

次のステップ

• Cloud Storage FUSE のトラブルシューティング
• Pod 仕様に沿ってバケットを指定し、Cloud Storage バケットをマウントする方法を確認する
• PersistentVolume リソースを使用して Cloud Storage バケットをマウントする方法を確認する
• Workload Identity Federation for GKE を使用するようにアプリケーションを構成する方法を確認する。
• Cloud Storage FUSE プロファイルを使用してパフォーマンスを自動的に最適化する
• パフォーマンスを最適化するように Cloud Storage FUSE を手動で調整する