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

Autopilot Standard

---

このページでは、GKE 用の Cloud Storage FUSE CSI ドライバを設定して使用する準備をする方法について説明します。

Cloud Storage FUSE CSI ドライバを使用する手順は次のとおりです。

• Cloud Storage バケットを作成する
• ドライバを有効にする
• Cloud Storage バケットへのアクセスを構成する

Cloud Storage バケットを作成する

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

ヒント: Cloud Storage バケットと GKE クラスタは、異なる Google Cloud プロジェクトに配置することも、同じプロジェクトに配置することもできます。

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

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

Autopilot

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

標準

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 バケットを使用して、GKE 用 Workload Identity 連携で認証します。

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 ServiceAccount に使用する 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 Object ユーザーロールを使用します（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 Object ユーザーロールを使用します（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 のトラブルシューティング
• パフォーマンスを最適化するように Cloud Storage FUSE を調整する
• Pod 仕様に沿ってバケットを指定して Cloud Storage バケットをマウントする方法を確認する。
• PersistentVolume リソースを使用して Cloud Storage バケットをマウントする方法を確認する。
• Workload Identity Federation for GKE を使用するようにアプリケーションを構成する方法について学習する。