將 Cloud Storage bucket 掛接為 CSI 暫時磁碟區

本指南說明如何使用 Cloud Storage bucket 支援的 CSI 臨時磁碟區，自動管理 Google Kubernetes Engine (GKE) 上 Kubernetes Pod 或 Job 的儲存空間資源。CSI 暫時磁碟區會繫結至 Pod 或工作的生命週期，您不需要手動處理 PersistentVolume 和 PersistentVolumeClaim 物件。

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

閱讀本頁內容前，請務必熟悉 CSI 臨時磁碟區、Kubernetes Pod 和工作，以及 Cloud Storage bucket。

如果您已熟悉 PersistentVolume，且希望與現有部署作業保持一致，請參閱「將 Cloud Storage bucket 掛接為永久磁碟區」。

事前準備

請確認您已完成下列事前準備事項：

Cloud Storage bucket 的 CSI 暫時性儲存空間運作方式

CSI 暫時磁碟區可簡化 GKE 應用程式的儲存空間管理作業。您可以在 Pod 或 Job 規格中直接定義 CSI 臨時磁碟區。使用 CSI 臨時磁碟區時，不需要個別的 PersistentVolume 和 PersistentVolumeClaim 物件。

使用 CSI 暫時性磁碟區時，需要執行下列作業：

  1. 儲存空間定義：您可以在 Pod 或 Job 的 YAML 檔案中指定儲存空間，包括要使用的 CSI 驅動程式和任何必要參數。如果是 Cloud Storage FUSE CSI 驅動程式，請指定 bucket 名稱和其他相關詳細資料。

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

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

  2. 驅動程式叫用：建立 Pod 或 Job 時，GKE 會偵測到暫時磁碟區要求，並呼叫 Cloud Storage FUSE CSI 驅動程式。

  3. 掛接及附加磁碟區：CSI 驅動程式會掛接 CSI 臨時磁碟區 (指向基礎 Cloud Storage bucket)，並提供給 Pod 或工作，讓應用程式可以存取。如要微調檔案系統中 Bucket 的掛接方式，可以使用掛接選項。您也可以使用磁碟區屬性，設定 Cloud Storage FUSE CSI 驅動程式的特定行為。

  4. 生命週期管理：臨時磁碟區的生命週期與 Pod 或 Job 相同。刪除 Pod 或 Job 完成時，CSI 驅動程式會自動處理清除作業，並卸載磁碟區。

附加 CSI 暫時磁碟區

請根據您要將 CSI 暫時性磁碟區附加至 Pod 或 Job，按照下列操作說明操作。

Pod

如要在 Pod 中連接 CSI 暫時磁碟區，請按照下列步驟操作：

  1. 使用下列規格建立 Pod 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"

    替換下列值：

    • NAMESPACE：要部署 Pod 的 Kubernetes 命名空間。
    • KSA_NAME：設定 Cloud Storage bucket 存取權時指定的 Kubernetes ServiceAccount 名稱。
    • BUCKET_NAME：設定 Cloud Storage bucket 存取權時指定的 Cloud Storage bucket 名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有值區。詳情請參閱 Cloud Storage FUSE 說明文件的「動態掛接」一節。

    資訊清單範例顯示了以下必要設定：

    • metadata.annotations：必須使用 gke-gcsfuse/volumes: "true" 註解。如要瞭解選用註解，請參閱「設定邊車容器」。
    • spec.volumes[n].csi.driver：使用 gcsfuse.csi.storage.gke.io 做為 CSI 驅動程式名稱。

    您也可以視需要調整下列變數：

    • spec.terminationGracePeriodSeconds：預設值為 30。如要將大型檔案寫入 Cloud Storage bucket，請提高這個值，確保 Cloud Storage FUSE 有足夠時間在應用程式結束後清除資料。詳情請參閱「Kubernetes 最佳做法：安全終止」。
    • spec.volumes[n].csi.volumeAttributes.mountOptions：將掛接選項傳遞至 Cloud Storage FUSE。請在一個以半形逗號分隔的字串中指定旗標，不要加上空格。
    • 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 檔案的路徑。

Pod (檔案快取)

如要在 Pod 中附加 CSI 臨時磁碟區並啟用檔案快取，請按照下列步驟操作：

  1. 按照「建立叢集或節點集區，並採用本機 SSD 支援的臨時儲存空間」一文中的步驟，建立叢集或節點集區，並採用本機 SSD 支援的臨時儲存空間。

  2. 使用下列規格建立 Pod 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
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  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,file-cache:max-size-mb:-1"

    替換下列值：

    • NAMESPACE：要部署 Pod 的 Kubernetes 命名空間。
    • KSA_NAME：您在設定 Cloud Storage bucket 存取權時指定的 Kubernetes ServiceAccount 名稱。

    • BUCKET_NAME：設定 Cloud Storage bucket 存取權時指定的 Cloud Storage bucket 名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有值區。詳情請參閱 Cloud Storage FUSE 說明文件中的「動態掛接」。

      在範例資訊清單中，init container 資料載入器會產生 1,000 個大小為 64 KiB 的檔案，並將這些檔案上傳至 Cloud Storage bucket。主要容器 data-validator 會從 bucket 讀取所有檔案兩次，並記錄時間長度。

  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
...

    輸出內容顯示，使用本機快取的第二次讀取速度，比快取失敗的第一次讀取快得多。

Pod (平行下載)

如要在 Pod 中附加 CSI 臨時磁碟區並行下載，請按照下列步驟操作：

  1. 使用下列規格建立 Pod YAML 資訊清單：

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral 
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
        fileCacheCapacity: "-1"

    替換下列值：

    • NAMESPACE：要部署 Pod 的 Kubernetes 命名空間。
    • BUCKET_NAME：設定 Cloud Storage bucket 存取權時指定的 Cloud Storage bucket 名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有 bucket。詳情請參閱 Cloud Storage FUSE 說明文件的「動態掛接」一節。

  2. 執行下列指令，將資訊清單套用至叢集：

    kubectl apply -f FILE_PATH

    將 FILE_PATH 替換為 YAML 檔案的路徑。

工作

如要在 Job 中附加 CSI 臨時磁碟區，請按照下列步驟操作：

  1. 使用下列規格建立 Job 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：部署 Pod 的 Kubernetes 命名空間。
    • KSA_NAME：您在設定 Cloud Storage bucket 存取權時指定的 Kubernetes ServiceAccount 名稱。
    • BUCKET_NAME：設定 Cloud Storage bucket 存取權時指定的 Cloud Storage bucket 名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有 bucket。詳情請參閱 Cloud Storage FUSE 說明文件中的「動態掛接」。

    以下是資訊清單範例，顯示這些必要設定：

    • metadata.annotations：必須提供註解 gke-gcsfuse/volumes: "true"。如要瞭解選用註解，請參閱「設定邊車容器」。
    • spec.volumes[n].csi.driver：使用 gcsfuse.csi.storage.gke.io 做為 CSI 驅動程式名稱。

    您也可以視需要調整下列變數：

    • spec.volumes[n].csi.volumeAttributes.mountOptions：將掛接選項傳遞至 Cloud Storage FUSE。請在一個以半形逗號分隔的字串中指定旗標，不要加上空格。
    • 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 臨時磁碟區掛接同一個 Cloud Storage bucket

您也可以使用多個 CSI 臨時磁碟區，這些磁碟區由同一個 Cloud Storage bucket 提供支援。方法是附加兩個以上的磁碟區，並在不同的掛接路徑參照相同的 bucket 名稱。舉例來說，您可以將具有不同掛接選項的不同 CSI 臨時磁碟區掛接至同一個 Pod，而每個臨時磁碟區都參照同一個 Cloud Storage bucket。以下是使用這項功能的 Pod 資訊清單範例：

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
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral-with-mo
          mountPath: /data2
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      - name: gcs-fuse-csi-ephemeral-with-mo
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
            mountOptions: "implicit-dirs"
      restartPolicy: Never
  backoffLimit: 1

排解問題

如要進一步瞭解如何排解 Cloud Storage FUSE CSI 驅動程式問題，請參閱 GitHub 專案說明文件中的疑難排解指南。

後續步驟