為 GKE 設定 Cloud Storage FUSE CSI 驅動程式

自動駕駛 標準

---

本頁說明如何設定及準備使用 GKE 的 Cloud Storage FUSE CSI 驅動程式。

如要使用 Cloud Storage FUSE CSI 驅動程式，請完成下列步驟：

• 建立 Cloud Storage bucket
• 啟用驅動程式
• 設定 Cloud Storage 值區的存取權

建立 Cloud Storage 值區

如果尚未建立 Cloud Storage 值區，請建立值區。 您會在 GKE 叢集中將這些 bucket 掛接為磁碟區。為提升效能，請將「位置類型」設為「區域」，並選取與 GKE 叢集相符的區域。

提示： Cloud Storage 值區和 GKE 叢集可以位於不同 Google Cloud 專案，也可以位於相同專案。

啟用 Cloud Storage FUSE CSI 驅動程式

請按照下列步驟操作，具體做法取決於您使用的是 GKE Autopilot 或 Standard 叢集。建議您使用 Autopilot 叢集，享受全代管的 Kubernetes 體驗。如要選擇最適合工作負載的模式，請參閱「選擇 GKE 作業模式」。

Autopilot

Autopilot 叢集預設會啟用 Cloud Storage FUSE CSI 驅動程式。您可以直接跳到「設定 Cloud Storage 值區的存取權」。

標準

如果 Standard 叢集已啟用 Cloud Storage FUSE CSI 驅動程式，請跳至「設定 Cloud Storage bucket 的存取權」。

Standard 叢集預設不會啟用 Cloud Storage FUSE CSI 驅動程式。如要建立啟用 Cloud Storage FUSE CSI 驅動程式的標準叢集，可以使用 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。

如要在現有標準叢集上啟用驅動程式，請使用 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 驅動程式使用 GKE 適用的工作負載身分聯盟，因此您可以針對 GKE Pod 存取 Cloud Storage 中儲存資料的方式，設定精細的權限。

如要讓 GKE 叢集存取 Cloud Storage 值區，請使用 Workload Identity Federation for GKE 進行驗證，並在 Pod 規格中掛接所需的 Cloud Storage 值區：

1. 如果尚未啟用 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 的命名空間。您也可以使用 default 命名空間或任何現有命名空間。

   kubectl create namespace NAMESPACE
   

   將 NAMESPACE 替換為 Kubernetes ServiceAccount 的 Kubernetes 命名空間名稱。

   重要事項： 工作負載必須在同一個命名空間中執行。

4. 為應用程式建立要使用的 Kubernetes ServiceAccount。您也可以在任何命名空間中使用現有的 Kubernetes ServiceAccount，包括 default Kubernetes ServiceAccount。

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   將 KSA_NAME 替換為 Kubernetes ServiceAccount 的名稱。

5. 將其中一個 Cloud Storage 適用的 IAM 角色授予 Kubernetes ServiceAccount。請按照下列步驟操作，視您是要授予 Kubernetes ServiceAccount 存取特定 Cloud Storage 值區的權限，還是授予專案中所有值區的存取權而定。

   特定 bucket 存取權

   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 bucket 名稱。
   • PROJECT_NUMBER：GKE 叢集的數值專案編號。 如要找出專案編號，請參閱「識別專案」。
   • PROJECT_ID：GKE 叢集的專案 ID。
   • NAMESPACE：Kubernetes ServiceAccount 的 Kubernetes 命名空間名稱。
   • KSA_NAME：新 Kubernetes ServiceAccount 的名稱。
   • ROLE_NAME：要指派給 Kubernetes ServiceAccount 的 IAM 角色。
     • 如果是唯讀工作負載，請使用「Storage 物件檢視者」角色 (roles/storage.objectViewer)。
     • 如為讀寫工作負載，請使用 Storage Object User 角色 (roles/storage.objectUser)。

   全域 bucket 存取權

   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 命名空間名稱。
   • KSA_NAME：新 Kubernetes ServiceAccount 的名稱。
   • ROLE_NAME：要指派給 Kubernetes ServiceAccount 的 IAM 角色。
     • 如果是唯讀工作負載，請使用「Storage 物件檢視者」角色 (roles/storage.objectViewer)。
     • 如為讀寫工作負載，請使用 Storage Object User 角色 (roles/storage.objectUser)。

為使用主機網路的 Pod 設定存取權

如果 GKE 叢集版本早於 1.33.3-gke.1226000，由於 GKE 工作負載身分聯盟的限制，Cloud Storage FUSE CSI 驅動程式不支援在主機網路 (hostNetwork: true) 上執行的 Pod。不過，如果是較新的 GKE 版本，使用 Cloud Storage FUSE CSI 驅動程式掛接 Cloud Storage bucket 時，可以為已啟用 hostNetwork 的 Pod 設定安全驗證。主機網路支援僅適用於 Standard GKE 叢集。

請確認 GKE 叢集符合下列規定：

• Standard GKE 叢集中的控制層和節點集區都必須是 1.33.3-gke.1226000 以上版本。
• 在叢集上啟用 Workload Identity。
• 將必要的 IAM 權限授予 Kubernetes 服務帳戶，讓啟用 hostNetwork 的 Pod 能存取 Cloud Storage 值區。詳情請參閱「向 Cloud Storage FUSE 進行驗證」。

在 Pod 或 PersistentVolume 定義中指定磁碟區屬性 hostNetworkPodKSA: "true"，即可讓 HostNetwork Pod 存取 Cloud Storage 磁碟區。實際設定方式取決於您管理 Cloud Storage FUSE Sidecar 容器的方式。

代管的 Sidecar

如果 GKE 會自動將 Cloud Storage FUSE Sidecar 容器插入 Pod 並進行管理，則適用本節內容。這個選項是 Cloud Storage FUSE CSI 驅動程式的預設設定，也是建議的設定。

暫時磁碟區

下列 Pod 資訊清單會為 HostNetwork Pod 設定臨時磁碟區，以便存取 Cloud Storage bucket。

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 設定 PV，以便存取 Cloud Storage bucket。

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"

私有 Sidecar

如果您在 Pod 中手動管理 Cloud Storage FUSE Sidecar 容器，或使用自訂 Sidecar 映像檔，請參閱本節內容。

確認 Sidecar 映像檔是以 Cloud Storage FUSE CSI 驅動程式 v1.17.2 以上版本為基礎。

暫時磁碟區

下列 Pod 資訊清單會為 HostNetwork Pod 設定臨時磁碟區，以便存取 Cloud Storage bucket。

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 設定 PV，以便存取 Cloud Storage bucket。

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 規格中內嵌指定 bucket，掛接 Cloud Storage bucket。
• 瞭解如何使用 PersistentVolume 資源掛接 Cloud Storage 值區。
• 進一步瞭解如何設定應用程式，以使用 GKE 適用的工作負載身分聯盟。