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

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

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

閱讀本頁面之前，請務必先熟悉 CSI 臨時磁碟區、Kubernetes Pod 和 Job，以及 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 值區)，並提供給 Pod 或 Job，讓應用程式可以存取。如要微調值區在檔案系統中的掛接方式，可以使用掛接選項。您也可以使用磁碟區屬性設定 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 值區的存取權時指定的 Kubernetes ServiceAccount 名稱。
    • BUCKET_NAME：設定 Cloud Storage 值區存取權時指定的值區名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有值區。詳情請參閱 Cloud Storage FUSE 說明文件中的動態掛接。

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

    • metadata.annotations：必須提供 gke-gcsfuse/volumes: "true" 註解。如需選用註解，請參閱「設定 Sidecar 容器」。
    • 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 值區存取權時指定的值區名稱。您可以指定底線 (_)，掛接 Kubernetes ServiceAccount 可存取的所有值區。詳情請參閱 Cloud Storage FUSE 說明文件中的動態掛接。

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

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

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

    • metadata.annotations：必須提供 gke-gcsfuse/volumes: "true" 註解。如需選用註解，請參閱「設定 Sidecar 容器」。
    • 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 檔案的路徑。

排解問題

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

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

後續步驟