為 GKE 設定 Cloud Storage FUSE CSI 驅動程式邊車容器

本指南說明如何為 Cloud Storage FUSE CSI 驅動程式邊車容器設定資源，包括設定私人映像檔、自訂寫入緩衝區和自訂讀取快取磁碟區。一般來說，您不需要變更這些設定。

Cloud Storage FUSE CSI 驅動程式會使用可自訂的邊車容器，有效率地掛接及存取 Cloud Storage bucket。設定 Sidecar 後，您可以微調應用程式效能和資源用量，進而加快資料存取速度、縮短處理時間，並可能降低應用程式的整體資源耗用量。

本指南適用於開發人員、管理員和架構師，可協助他們提升與 GKE 互動的應用程式效能、安全性和效率。

閱讀本頁面之前，請務必先熟悉 Cloud Storage、Kubernetes 和容器化概念的基本知識。

邊車容器的運作方式

Cloud Storage FUSE CSI 驅動程式會使用邊車容器掛接 Cloud Storage bucket，讓 Kubernetes 應用程式可將這些 bucket 當成本機檔案系統存取。這個名為 gke-gcsfuse-sidecar 的邊車容器，會在同一個 Pod 中與工作負載容器並行執行。當驅動程式在 Pod 規格中偵測到 gke-gcsfuse/volumes: "true" 註解時，就會自動插入邊車容器。這種邊車容器方法有助於確保安全性，並有效管理資源。

邊車容器會處理掛接 Cloud Storage bucket 的複雜作業，並為應用程式提供檔案系統存取權，您不必直接管理 Cloud Storage FUSE 執行階段。您可以使用 gke-gcsfuse/cpu-limit 和 gke-gcsfuse/memory-limit 等註解，為邊車容器設定資源限制。邊車容器模型也能確保 Cloud Storage FUSE 執行個體與工作負載生命週期繫結，避免不必要地耗用資源。也就是說，當工作負載容器結束時，邊車容器會自動終止，尤其是在工作負載或 Pod 中，RestartPolicy 為 Never 的情況。

Cloud Service Mesh 和 OSS Istio 相容性

Cloud Storage FUSE CSI 驅動程式的邊車容器和 Istio 可以共存，並在 Pod 中同時執行。不過，在 GKE 1.29 以上版本中，如果 Cloud Storage FUSE 嘗試在 Istio Proxy 準備就緒前連線至中繼資料伺服器，可能會發生驗證失敗的情況。如果遇到這些驗證失敗情形，只要在 Pod 規格的 metadata.annotations 中加入 traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32，即可解決問題。這項註解會設定 Istio 或 Cloud Service Mesh，將 GKE 中繼資料伺服器的 IP 位址排除在重新導向之外。

設定自訂寫入緩衝區

Cloud Storage FUSE 會在本機目錄中暫存寫入作業，然後在 close 或 fsync 作業中上傳至 Cloud Storage。

本節說明如何為 Cloud Storage FUSE 寫入緩衝設定自訂緩衝區容量。如果您需要取代 Cloud Storage FUSE 的預設 emptyDir 磁碟區，以便在寫入作業中暫存檔案，可能就適用這個情境。如果您需要在 Autopilot 叢集上寫入大於 10 GiB 的檔案，這項功能就非常實用。

您可以指定 Cloud Storage FUSE CSI 驅動程式支援的任何類型儲存空間，用於檔案快取，例如本機 SSD、以 Persistent Disk 為基礎的儲存空間，以及 RAM 磁碟 (記憶體)。GKE 會使用指定的磁碟區做為檔案寫入緩衝區。如要進一步瞭解這些選項，請參閱「選取備份檔案快取的儲存空間」。

如要使用 Persistent Disk 支援的自訂緩衝區磁碟區，您必須在 Pod 的 securityContext 中指定非零的 fsGroup。這個步驟會將磁碟區的必要讀取或寫入權限授予非根目錄的 Sidecar 容器。如果 PVC 將 Cloud Storage bucket 掛接為永久磁碟區，則不需要使用 Cloud Storage FUSE CSI 驅動程式。

以下範例說明如何使用預先定義的 PersistentVolumeClaim 做為緩衝區磁碟區：

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

更改下列內容：

  • FS_GROUP：fsGroup ID。
  • BUFFER_VOLUME_PVC：預先定義的 PVC 名稱。

設定自訂讀取快取磁碟區

本節說明如何為 Cloud Storage FUSE 讀取快取設定自訂快取磁碟區。

如果您需要取代 Cloud Storage FUSE 的預設 emptyDir 磁碟區，以便在讀取作業中快取檔案，可能就適用這個情境。您可以指定 GKE 支援的任何儲存空間類型，例如 PersistentVolumeClaim，GKE 會使用指定的磁碟區進行檔案快取。如果您需要在 Autopilot 叢集上快取大於 10 GiB 的檔案，這項功能就非常實用。

如要使用 Persistent Disk 支援的自訂快取磁碟區，您必須在 Pod 的 securityContext 中指定非零的 fsGroup。這個步驟會將磁碟區的必要讀取或寫入權限授予非根目錄的 Sidecar 容器。如果 PVC 將 Cloud Storage bucket 掛接為 Persistent Volume，則不需要使用 Cloud Storage FUSE CSI 驅動程式，

以下範例說明如何使用預先定義的 PersistentVolumeClaim 做為快取磁碟區：

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

更改下列內容：

  • FS_GROUP：fsGroup ID。
  • CACHE_VOLUME_PVC：預先定義的 PersistentVolumeClaim 名稱。

為邊車容器設定私人映像檔

本節說明如何在私人容器登錄檔中託管邊車容器映像檔。如果您需要使用私有節點來確保安全性，可能就適用這個情境。

如要設定及使用私有邊車容器映像檔，請按照下列步驟操作：

  1. 請參閱這份 GKE 相容性表格，找出相容的公開邊車容器映像檔。
  2. 將其提取至本機環境，然後推送至私人容器登錄檔。

  3. 在資訊清單中，指定名為 gke-gcsfuse-sidecar 的容器，其中只包含映像檔欄位。GKE 會使用指定的邊車容器映像檔，準備注入邊車容器。

    範例如下：

    apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

    更改下列內容：

    • PRIVATE_REGISTRY：私人容器登錄檔。例如：us-central1-docker.pkg.dev/my-project/my-registry。
    • PRIVATE_IMAGE_TAG：您的私有邊車容器映像檔標記。例如：v1.17.1-gke.1。

設定邊車容器資源

根據預設，系統會為 Standard 和 Autopilot 叢集的 gke-gcsfuse-sidecar 容器設定下列資源要求和限制：

要求：

  • 250m CPU
  • 256 MiB 記憶體
  • 5 GiB 臨時儲存空間

限制 (GKE 1.29.1-gke.1670000 以上版本)：

  • 無限制 CPU
  • 無限記憶體
  • 無限暫存空間

限制 (GKE 版本 1.29.1-gke.1670000 之前)：

  • 250m CPU
  • 256 MiB 記憶體
  • 5 GiB 臨時儲存空間

根據預設，系統會為 Standard 和 Autopilot 叢集的 gke-gcsfuse-metadata-prefetch 容器設定下列資源要求和限制：

要求：

  • 10 分鐘 CPU
  • 10 MiB 記憶體
  • 10 MiB 暫存空間

限制：

  • 50m CPU
  • 250 MiB 記憶體
  • 無限暫存空間

在 Standard 和 Autopilot 叢集中，您可以覆寫預設值。GKE 處理容器資源的方式取決於叢集作業模式：

  • 標準叢集：如果設定要求或限制，但未設定另一項，系統會將 Pod 的資源限制和要求設為相同。如果同時設定要求和限制，Pod 會使用您指定的確切資源要求和限制。如未設定任何值，系統會直接套用預設資源 (如上所述)。
  • Autopilot 叢集：如果設定了要求或限制，但未設定另一項，系統會將 Pod 的資源限制和要求設為相同。請參閱「在 Autopilot 中設定資源限制」，瞭解資源覆寫和預設資源值設定對 Pod 行為的影響。

如要覆寫 gke-gcsfuse-sidecar 容器的預設值，您可以選擇指定 gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] 註解，如下列範例所示：

如要覆寫 gke-gcsfuse-metadata-prefetch 容器的預設值 (從 GKE 版本 1.32.3-gke.1717000 開始)，您可以選擇性地指定註解 gke-gcsfuse/[metadata-prefetch-cpu-limit|metadata-prefetch-memory-limit|metadata-prefetch-ephemeral-storage-limit|metadata-prefetch-cpu-request|metadata-prefetch-memory-request|metadata-prefetch-ephemeral-storage-request]，如下列範例所示：

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"

    # gke-gcsfuse-sidecar overrides
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

    # gke-gcsfuse-metadata-prefetch overrides
    gke-gcsfuse/metadata-prefetch-cpu-limit: "10"
    gke-gcsfuse/metadata-prefetch-memory-limit: 10Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-limit: 1Ti
    gke-gcsfuse/metadata-prefetch-cpu-request: 500m
    gke-gcsfuse/metadata-prefetch-memory-request: 1Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-request: 50Gi

您可以使用值 "0" 取消設定任何資源限制或要求，但請注意，gke-gcsfuse-sidecar 容器已取消設定所有限制 (cpu-limit、memory-limit 和 ephemeral-storage-limit)，且 gke-gcsfuse-metadata-prefetch 容器已取消設定 ephemeral-storage-limit，因此在 GKE 1.32.3-gke.1717000 以上版本的叢集上將這些限制設為 "0"，不會有任何作用。

舉例來說，設定 gke-gcsfuse/metadata-prefetch-memory-limit: "0" 表示您要取消設定 gke-gcsfuse-metadata-prefetch 容器記憶體限制。如果您無法決定中繼資料預先擷取功能需要多少資源來處理工作負載，並希望中繼資料預先擷取功能耗用節點上的所有可用資源，這項功能就非常實用。

(選用) 使用 Cloud Profiler 分析效能

您可以使用 Cloud Profiler，持續且精細地掌握儲存空間用量大的應用程式資源消耗情形。這些詳細資料可協助您主動監控 Cloud Storage FUSE CSI 驅動程式及其附屬容器的 CPU 和記憶體用量。從 Cloud Profiler 資料取得的洞察資訊，有助於找出效率不彰的程式碼路徑、最佳化資源分配，以及在記憶體流失或發生非預期的記憶體不足 (OOM) 事件影響服務穩定性之前，排解這類複雜問題。

您可以選擇是否使用 Cloud Profiler，這項工具專為需要詳細效能診斷的管理員設計。節點驅動程式預設會啟用 Cloud Profiler。如果是補充容器，這項功能是選用功能，您可以手動啟用。

啟用 Cloud Profiler 前

如要搭配 Cloud Storage FUSE CSI 驅動程式使用 Cloud Profiler，請確認您使用的是 GKE 1.36.0-gke.2403000 以上版本。產生剖析資料前，請先啟用 Cloud Profiler API，並為要剖析的元件設定適當的 IAM 權限。

啟用 API

啟用 Cloud Profiler API

授予節點驅動程式權限

如要將剖析資料傳送至 Cloud Profiler，節點驅動程式必須具備 IAM 權限。由於節點驅動程式預設會在主機網路上執行，因此會使用與 GKE 節點相關聯的 IAM 服務帳戶進行驗證，而不是使用 Workload Identity Federation for GKE。

將 roles/cloudprofiler.agent 角色授予節點的服務帳戶：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=serviceAccount:NODE_SERVICE_ACCOUNT

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • NODE_SERVICE_ACCOUNT：GKE 節點使用的 IAM 服務帳戶。除非節點設定為使用其他服務帳戶，否則這通常是預設的 Compute Engine 服務帳戶，例如 PROJECT_NUMBER-compute@。

授予 Sidecar 容器權限

如要將剖析資料傳送至 Cloud Profiler，邊車容器和 gcsfuse 程序必須具備 IAM 權限。這些元件會使用 Workload Identity Federation for GKE 進行驗證，後者會使用與工作負載 Pod 相關聯的 Kubernetes 服務帳戶 (KSA)。

將 roles/cloudprofiler.agent 角色授予 Pod 使用的 KSA：

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • PROJECT_NUMBER： Google Cloud 專案的專案編號。
  • NAMESPACE：Kubernetes 命名空間的名稱。
  • KSA_NAME：Kubernetes 服務帳戶的名稱。

為 Sidecar 工作負載啟用 Cloud Profiler

如要為 Sidecar Mounter 和基礎 gcsfuse 程序產生設定檔，請在工作負載規格中將 enableCloudProfilerForSidecar 磁碟區屬性設為 "true"。為邊車容器啟用 Cloud Profiler 時，系統也會自動為基礎 gcsfuse 程序啟用這項功能。

將 BUCKET_NAME 替換為 Cloud Storage 值區名稱：

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"

查看剖析資料

如要查看剖析資料，請前往 Google Cloud 控制台的「Cloud Profiler」頁面。使用「服務名稱」篩選器，分析您正在調查的元件：

元件 服務名稱篩選器
節點驅動程式 gcs-fuse-csi-driver
Sidecar Mounter gke-gcsfuse-sidecar
GCSFuse gcsfuse

Cloud Profiler 會使用 POD_NAME_POD_UID 格式識別每個執行個體。即使 Pod 重新啟動，這也能確保每個執行個體都有專屬 ID。

(選用) 停用 GCSFuse 剖析功能

根據預設，啟用邊車容器的剖析功能時，系統也會剖析基礎 gcsfuse 程序。您可能想停用 gcsfuse 剖析功能，以減少資源負擔，或只專注於分析 Sidecar 容器的效能。

如要停用 gcsfuse 剖析功能，但保持啟用 Sidecar 剖析功能，請在磁碟區規格的 mountOptions 屬性中加入 enable-cloud-profiler=false。

將 BUCKET_NAME 替換為 Cloud Storage 值區名稱：

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"
        mountOptions: "enable-cloud-profiler=false"

設定記錄詳細程度

根據預設，gke-gcsfuse-sidecar 容器會在 info 和 error 層級產生記錄。 不過，如要進行偵錯或更詳細的分析，可能需要調整記錄詳細程度。本節說明如何提高或降低記錄層級。

您可以透過掛接選項設定記錄詳細程度，也可以使用 CSI 驅動程式的功能，將磁碟區屬性值轉換為必要的 gcsfuse 設定。

在目標 Pod 資訊清單中，加入下列設定：

      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity:  LOGGING_SEVERITY

如要使用掛接選項，請在目標 Pod 資訊清單中加入下列設定：

  mountOptions: "logging:severity:LOGGING_SEVERITY"

更改下列內容：

  • BUCKET_NAME：Cloud Storage bucket 名稱。
  • LOGGING_SEVERITY：根據您的需求，使用下列其中一個值：
    • trace
    • debug
    • info
    • warning
    • error

部署 Pod 後，CSI 驅動程式會使用新設定的記錄層級啟動 gcsfuse。

您可以使用下列篩選器，確認是否已套用記錄嚴重性：

resource.labels.container_name="gke-gcsfuse-sidecar"
resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
"severity:"

排解問題

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

後續步驟