將 Cloud Storage 值區掛接為永久磁碟區

本指南說明如何使用 Cloud Storage bucket 支援的 Kubernetes 永久磁碟區，管理 Google Kubernetes Engine (GKE) 上 Kubernetes Pod 的儲存空間資源。如果您已熟悉 PersistentVolume，且希望與現有部署作業保持一致，請考慮使用這個儲存空間選項。

本指南適用於平台管理員和運算子使用者，可協助他們簡化 GKE 應用程式的儲存空間管理作業。

閱讀本頁面之前，請務必先熟悉 Kubernetes 永久磁碟區、Kubernetes Pod 和 Cloud Storage 值區。

如要使用簡化的 Pod 介面，且不需要 Kubernetes 永久磁碟區的經驗，請參閱「將 Cloud Storage bucket 掛接為 CSI 暫時性磁碟區」。

事前準備

請確認您已完成下列必要條件：

Cloud Storage bucket 的永久磁碟區運作方式

透過靜態佈建，您可以建立一或多個 PersistentVolume 物件，其中包含基礎儲存系統的詳細資料。叢集中的 Pod 隨後就能透過 PersistentVolumeClaims 使用儲存空間。

使用 Cloud Storage bucket 支援的永久磁碟區時，需要執行下列作業：

  1. 儲存空間定義：在 GKE 叢集中定義 PersistentVolume，包括要使用的 CSI 驅動程式和任何必要參數。如果是 Cloud Storage FUSE CSI 驅動程式，請指定 bucket 名稱和其他相關詳細資料。

    您可以視需要使用檔案快取功能，微調 CSI 驅動程式的效能。檔案快取功能可將經常存取的 Cloud Storage 檔案快取到速度較快的本機磁碟，進而提升 GKE 應用程式效能。

    此外，您可以使用平行下載功能，加快從 Cloud Storage 讀取大型檔案的速度，以進行多執行緒下載。這項功能可縮短模型載入時間，特別是讀取超過 1 GB 的檔案時。

  2. 驅動程式叫用：當 PersistentVolumeClaim 要求與 PersistentVolume 規格相符的儲存空間時，GKE 會叫用 Cloud Storage FUSE CSI 驅動程式。

  3. 儲存空間掛接：CSI 驅動程式會將儲存空間掛接至排定要求 Pod 的節點。這樣一來，Pod 就能以 Pod 本機檔案系統中的目錄形式存取 Bucket 內容。如要微調值區在檔案系統中的掛接方式，可以使用掛接選項。您也可以使用磁碟區屬性設定 Cloud Storage FUSE CSI 驅動程式的特定行為。

  4. 重新連結：如果 Pod 重新啟動或重新排程至其他節點，CSI 驅動程式會將相同 bucket 重新掛接到新節點，確保資料可存取。

建立 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 命名空間。
    • BUCKET_NAME：您在設定 Cloud Storage bucket 的存取權時指定的 Cloud Storage bucket 名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有值區。詳情請參閱 Cloud Storage FUSE 說明文件中的動態掛接。

    資訊清單範例會顯示這些必要設定：

    • spec.csi.driver：請使用 gcsfuse.csi.storage.gke.io 做為 CSI 驅動程式名稱。

    (選用) 你可以調整下列變數：

    • spec.mountOptions：將掛接選項傳遞至 Cloud Storage FUSE。 以半形逗號分隔，不加空格，在一個字串中指定旗標。
    • 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 命名空間。
    • BUCKET_NAME：設定 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 命名空間。
    • BUCKET_NAME：設定 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 命名空間。

    如要將 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"
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"。如需選用註解，請參閱「設定 Sidecar 容器」。

    (選用) 你可以調整下列變數：

    • 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 bucket {:#mount-same-bucket-different-pv}，適用於 GKE 1.33.0-gke.1932000 以上版本

如要使用多個不同的永久磁碟區掛接同一個 Cloud Storage 值區，您必須為每個永久磁碟區使用專屬的 volumeHandle。在 PersistentVolume 物件中，請使用 BUCKET_NAME:UNIQUE_SUFFIX 格式的 volumeHandle 欄位。將 BUCKET_NAME 替換為值區名稱，並將 UNIQUE_SUFFIX 替換為您想要的任何專屬 ID。例如：myBucket:xyz123。

舉例來說，您可以多次將同一個 Cloud Storage 值區掛接至同一個節點，每次掛接都使用一組不同的掛接選項。

排解問題

如要排解 Cloud Storage FUSE 問題，您可以將 log-severity 旗標設為 TRACE。您可以在部署 YAML 的驅動程式容器規格 args 區段中設定旗標。這會導致 gcsfuseLoggingSeverity 音量屬性自動設為追蹤。

如需其他疑難排解提示，請參閱 GitHub 專案文件中的疑難排解指南。

後續步驟