Sidecar-Container für den CSI-Treiber für Cloud Storage FUSE für GKE konfigurieren

In diesem Dokument wird beschrieben, wie Sie Ressourceneinstellungen für den Sidecar-Container des Cloud Storage FUSE-CSI-Treibers in Google Kubernetes Engine (GKE) konfigurieren.

Wenn Sie die Leistung und Ressourcennutzung Ihrer Anwendung in der GKE optimieren möchten, konfigurieren Sie bestimmte Ressourceneinstellungen für den Sidecar-Container des CSI-Treibers für Cloud Storage FUSE. Durch die Einrichtung dieser Ressourcen, z. B. eines privaten Images, eines benutzerdefinierten Schreibzwischenspeichers und eines benutzerdefinierten Lesecache-Volumes, können Sie besser steuern, wie Ihre Anwendungen mit Cloud Storage interagieren. Diese Konfigurationen können zu einem schnelleren Datenzugriff und kürzeren Verarbeitungszeiten führen und möglicherweise den gesamten Ressourcenverbrauch in Ihren GKE-Clustern reduzieren.

Dieses Dokument richtet sich an Entwickler, Administratoren und Architekten, die die Anwendungsleistung optimieren. Weitere Informationen zu gängigen Rollen und Beispielaufgaben, auf die wir in Google Cloud Inhalten verweisen, finden Sie unter Häufig verwendete GKE-Nutzerrollen und -Aufgaben.

Bevor Sie beginnen, sollten Sie sich mit den folgenden Konzepten für Arbeitslasten und Speicher vertraut machen:

Funktionsweise des Sidecar-Containers

Der Cloud Storage FUSE CSI-Treiber verwendet einen Sidecar-Container, um Cloud Storage-Buckets bereitzustellen, damit sie für Kubernetes-Anwendungen als lokale Dateisysteme zugänglich sind. Dieser Sidecar-Container mit dem Namen gke-gcsfuse-sidecar wird neben dem Arbeitslastcontainer im selben Pod ausgeführt. Wenn der Treiber die Annotation gke-gcsfuse/volumes: "true" in einer Pod-Spezifikation erkennt, wird der Sidecar-Container automatisch eingefügt. Dieser Sidecar-Container-Ansatz trägt dazu bei, die Sicherheit zu gewährleisten und Ressourcen effektiv zu verwalten.

Der Sidecar-Container übernimmt die Komplexität der Bereitstellung der Cloud Storage-Buckets und bietet Dateisystemzugriff auf die Anwendungen, ohne dass Sie die Cloud Storage FUSE-Laufzeit direkt verwalten müssen. Sie können Ressourcenlimits für den Sidecar-Container mit Annotationen wie gke-gcsfuse/cpu-limit und gke-gcsfuse/memory-limit konfigurieren. Das Sidecar-Containermodell sorgt außerdem dafür, dass die Cloud Storage FUSE-Instanz an den Lebenszyklus der Arbeitslast gebunden ist, sodass keine Ressourcen unnötig verbraucht werden. Das bedeutet, dass der Sidecar-Container automatisch beendet wird, wenn die Arbeitslastcontainer beendet werden, insbesondere bei Jobarbeitslasten oder Pods mit einem RestartPolicy von Never.

OSS-Istio-Kompatibilität

Der Sidecar-Container des Cloud Storage FUSE CSI-Treibers und Istio können gleichzeitig in Ihrem Pod ausgeführt werden. In GKE-Version 1.29 und höher können jedoch Authentifizierungsfehler auftreten, wenn Cloud Storage FUSE versucht, eine Verbindung zum Metadatenserver herzustellen, bevor der Istio-Proxy bereit ist. Wenn diese Authentifizierungsfehler auftreten, können Sie das Problem beheben, indem Sie traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32 zu metadata.annotations in Ihrer Pod-Spezifikation hinzufügen. Mit dieser Annotation wird Istio so konfiguriert, dass die IP-Adresse des GKE-Metadatenservers von der Weiterleitung ausgeschlossen wird.

Benutzerdefinierten Schreib-Zwischenspeicher konfigurieren

Cloud Storage FUSE stellt Schreibvorgänge in einem lokalen Verzeichnis bereit und lädt sie dann bei close- oder fsync-Vorgängen in Cloud Storage hoch.

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Zwischenspeicher-Volume für die Schreibvorgangzwischenspeicherung in Cloud Storage FUSE konfigurieren. Dieses Szenario kann zutreffen, wenn Sie das Standard-emptyDir-Volume für Cloud Storage FUSE ersetzen müssen, um die Dateien in Schreibvorgängen bereitzustellen. Dies ist nützlich, wenn Sie Dateien mit mehr als 10 GiB in Autopilot-Clustern schreiben müssen.

Sie können jeden vom Cloud Storage FUSE-CSI-Treiber unterstützten Speichertyp für das Datei-Caching angeben, z. B. eine lokale SSD, einen nichtflüchtigen Speicher und eine RAM-Disk (Arbeitsspeicher). GKE verwendet das angegebene Volume für die Zwischenspeicherung von Dateischreibvorgängen. Weitere Informationen zu diesen Optionen finden Sie unter Speicher für das Sichern Ihres Datei-Cache auswählen.

Wenn Sie ein benutzerdefiniertes Zwischenspeicher-Volume verwenden möchten, das von einer Persistent Disk unterstützt wird, müssen Sie im securityContext Ihres Pods einen Wert für fsGroup angeben, der nicht null ist. In diesem Schritt werden dem Sidecar-Container ohne Root-Berechtigungen die erforderlichen Lese- oder Schreibberechtigungen für das Volume gewährt. Diese Einstellung ist nicht erforderlich, wenn Ihr PVC Cloud Storage-Buckets als persistenten Volumes bereitstellt und dabei den CSI-Treiber für Cloud Storage FUSE verwendet.

Im folgenden Beispiel wird gezeigt, wie Sie einen vordefinierten PersistentVolumeClaim als Puffervolumen verwenden können:

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

Ersetzen Sie Folgendes:

  • FS_GROUP: die fsGroup-ID.
  • BUFFER_VOLUME_PVC ist der Name des vordefinierten PVC.

Benutzerdefiniertes Lese-Cache-Volume konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Cache-Volume für das Cloud Storage FUSE-Lese-Caching konfigurieren.

Dieses Szenario kann zutreffen, wenn Sie das Standardvolume emptyDir für Cloud Storage FUSE ersetzen müssen, um die Dateien bei Lesevorgängen im Cache zu speichern. Sie können jeden von GKE unterstützten Speichertyp angeben, z. B. einen PersistentVolumeClaim. GKE verwendet dann das angegebene Volume für das Datei-Caching. Dies ist nützlich, wenn Sie Dateien, die größer als 10 GiB sind, in Autopilot-Clustern im Cache speichern müssen.

Wenn Sie ein benutzerdefiniertes Cache-Volume verwenden möchten, das von einer Persistent Disk unterstützt wird, müssen Sie im securityContext Ihres Pods einen Wert für fsGroup angeben, der nicht null ist. In diesem Schritt werden dem Sidecar-Container ohne Root-Berechtigungen die erforderlichen Lese- oder Schreibberechtigungen für das Volume gewährt. Diese Einstellung ist nicht erforderlich, wenn Ihr PVC Cloud Storage-Buckets als persistente Volumes bereitstellt und dabei den CSI-Treiber für Cloud Storage FUSE verwendet.

Im folgenden Beispiel wird gezeigt, wie Sie einen vordefinierten PersistentVolumeClaim als Cache-Volume verwenden können:

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

Ersetzen Sie Folgendes:

  • FS_GROUP: die fsGroup-ID.
  • CACHE_VOLUME_PVC ist der Name des vordefinierten PersistentVolumeClaim.

Privates Image für den Sidecar-Container konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie das Sidecar-Container-Image verwenden, wenn Sie es in einer privaten Container-Registry hosten. Dieses Szenario kann zutreffen, wenn Sie aus Sicherheitsgründen private Knoten verwenden müssen.

So konfigurieren und verwenden Sie das private Sidecar-Container-Image:

  1. In dieser GKE-Kompatibilitätstabelle finden Sie ein kompatibles öffentliches Sidecar-Container-Image.
  2. Rufen Sie es in Ihrer lokalen Umgebung ab und übertragen Sie es in Ihre private Container Registry.

  3. Geben Sie im Manifest einen Container mit dem Namen gke-gcsfuse-sidecar und nur dem Image-Feld an. GKE verwendet das angegebene Sidecar-Container-Image, um die Sidecar-Container-Einfügung vorzubereiten.

    Hier ein Beispiel:

    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.

    Ersetzen Sie dabei Folgendes:

    • PRIVATE_REGISTRY: Ihre private Container-Registry. Beispiel: us-central1-docker.pkg.dev/my-project/my-registry.
    • PRIVATE_IMAGE_TAG: durch Ihr privates Sidecar-Container-Image-Tag. Beispiel: v1.17.1-gke.1.

Sidecar-Container-Ressourcen konfigurieren

Standardmäßig ist der gke-gcsfuse-sidecar-Container mit den folgenden Ressourcenanfragen und ‑limits für Standard- und Autopilot-Cluster konfiguriert:

Anfragen:

  • 250 mCPU
  • 256 MiB Arbeitsspeicher
  • Sitzungsspezifischer 5 GiB-Speicher

Grenzwerte (GKE-Version 1.29.1-gke.1670000 und höher):

  • Unbegrenzte CPU
  • unbegrenzter Speicherplatz
  • unbegrenzter flüchtiger Speicher

Limits (vor GKE-Version 1.29.1-gke.1670000):

  • 250 mCPU
  • 256 MiB Arbeitsspeicher
  • Sitzungsspezifischer 5 GiB-Speicher

Standardmäßig ist der gke-gcsfuse-metadata-prefetch-Container mit den folgenden Ressourcenanfragen und ‑limits für Standard- und Autopilot-Cluster konfiguriert:

Anfragen:

  • 10 mCPU
  • 10 MiB Arbeitsspeicher
  • 10 MiB sitzungsspezifischer Speicher

Beschränkungen:

  • 50 mCPU
  • 250 MiB Arbeitsspeicher
  • unbegrenzter flüchtiger Speicher

In Standard- und Autopilot-Clustern können Sie die Standardwerte überschreiben. Wie GKE Containerressourcen verarbeitet, hängt vom Betriebsmodus des Clusters ab:

  • Standardcluster: Wenn nur eine der beiden Einstellungen (Anfrage oder Limit) festgelegt ist, werden die Ressourcenlimits und -anfragen der Pods auf denselben Wert gesetzt. Wenn sowohl Anfragen als auch Limits festgelegt sind, verwenden Pods die von Ihnen angegebenen genauen Ressourcenanfragen und ‑limits. Wenn Sie keine Werte festlegen, werden die Standardressourcen (siehe oben) direkt angewendet.
  • Autopilot-Cluster: Wenn eine der Anfragen oder Limits festgelegt und eine andere nicht festgelegt ist, werden die Ressourcenlimits und -anfragen der Pods auf denselben Wert festgelegt. Unter Ressourcenlimits in Autopilot festlegen erfahren Sie, wie sich Ressourcenüberschreibungen und die festgelegten Standardressourcenwerte auf das Pod-Verhalten auswirken.

Wenn Sie die Standardwerte für den Container gke-gcsfuse-sidecar überschreiben möchten, können Sie optional die Annotation gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] angeben, wie im folgenden Beispiel gezeigt:

Wenn Sie die Standardwerte für den gke-gcsfuse-metadata-prefetch-Container (ab GKE-Version 1.32.3-gke.1717000) überschreiben möchten, können Sie optional die Annotation 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] angeben, wie im folgenden Beispiel gezeigt:

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

Mit dem Wert "0" können Sie alle Ressourcenlimits oder -anforderungen aufheben. Beachten Sie jedoch, dass für den gke-gcsfuse-sidecar-Container bereits alle Limits (cpu-limit, memory-limit und ephemeral-storage-limit) aufgehoben sind und für den gke-gcsfuse-metadata-prefetch-Container bereits ephemeral-storage-limit aufgehoben ist. Das Festlegen dieser Limits auf "0" in einem Cluster mit GKE-Version 1.32.3-gke.1717000 oder höher wäre also ein No-Op.

Wenn Sie beispielsweise gke-gcsfuse/metadata-prefetch-memory-limit: "0" festlegen, wird das Arbeitsspeicherlimit des Containers gke-gcsfuse-metadata-prefetch aufgehoben. Das ist nützlich, wenn Sie sich nicht sicher sind, wie viele Ressourcen die Funktion zum Vorabrufen von Metadaten für Ihre Arbeitslasten benötigt, und möchten, dass das Vorabrufen von Metadaten alle verfügbaren Ressourcen auf einem Knoten verbraucht.

(Optional) Leistung mit Cloud Profiler analysieren

Mit Cloud Profiler können Sie kontinuierlich und detailliert den Ressourcenverbrauch Ihrer speicherintensiven Anwendungen einsehen. Mit den detaillierten Daten können Sie die CPU- und Arbeitsspeicherauslastung im Cloud Storage FUSE-CSI-Treiber und seinem Sidecar-Container proaktiv überwachen. Die Erkenntnisse, die Sie aus Cloud Profiler-Daten gewinnen, können Ihnen helfen, ineffiziente Codepfade zu identifizieren, die Ressourcenzuweisung zu optimieren und komplexe Probleme wie Speicherlecks oder unerwartete OOM-Ereignisse (Out of Memory) zu beheben, bevor sie sich auf die Dienststabilität auswirken.

Die Verwendung von Cloud Profiler ist optional und für Administratoren gedacht, die detaillierte Leistungsdiagnosen benötigen. Cloud Profiler ist standardmäßig für den Knotentreiber aktiviert. Für Sidecar-Container ist es eine optionale Funktion, die Sie manuell aktivieren können.

Bevor Sie Cloud Profiler aktivieren

Wenn Sie Cloud Profiler mit dem Cloud Storage FUSE-CSI-Treiber verwenden möchten, müssen Sie GKE-Version 1.36.0-gke.2403000 oder höher verwenden. Bevor Sie Profile generieren können, müssen Sie die Cloud Profiler API aktivieren und die entsprechenden IAM-Berechtigungen für die Komponenten konfigurieren, die Sie profilieren möchten.

API aktivieren

Cloud Profiler API aktivieren

Berechtigungen für den Knotentreiber erteilen

Damit Profiling-Daten an Cloud Profiler gesendet werden können, benötigt der Knotentreiber IAM-Berechtigungen. Da der Knotentreiber standardmäßig im Hostnetzwerk ausgeführt wird, erfolgt die Authentifizierung über das IAM-Dienstkonto, das dem GKE-Knoten zugeordnet ist, anstatt über die Workload Identity-Föderation für GKE.

Weisen Sie dem Dienstkonto Ihres Knotens die Rolle roles/cloudprofiler.agent zu:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • NODE_SERVICE_ACCOUNT: das IAM-Dienstkonto, das von Ihren GKE-Knoten verwendet wird. Dies ist in der Regel das Compute Engine-Standarddienstkonto, z. B. PROJECT_NUMBER-compute@, sofern Ihre Knoten nicht für die Verwendung eines anderen Dienstkontos konfiguriert sind.

Berechtigungen für den Sidecar-Container erteilen

Zum Senden von Profiling-Daten an Cloud Profiler benötigen der Sidecar-Container und der gcsfuse-Prozess IAM-Berechtigungen. Diese Komponenten werden mit Workload Identity Federation for GKE authentifiziert. Dabei wird das Kubernetes-Dienstkonto (Kubernetes Service Account, KSA) verwendet, das mit dem Pod Ihrer Arbeitslast verknüpft ist.

Weisen Sie dem KSA, das von Ihrem Pod verwendet wird, die Rolle roles/cloudprofiler.agent zu:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • PROJECT_NUMBER: die Projektnummer Ihres Google Cloud -Projekts.
  • NAMESPACE: Der Name Ihres Kubernetes-Namespace.
  • KSA_NAME: der Name Ihres Kubernetes-Dienstkontos.

Cloud Profiler für Sidecar-Arbeitslasten aktivieren

Wenn Sie Profile für den Sidecar-Mounter und den zugrunde liegenden gcsfuse-Prozess generieren möchten, legen Sie in der Arbeitslastspezifikation das Volume-Attribut enableCloudProfilerForSidecar auf "true" fest. Wenn Sie Cloud Profiler für den Sidecar-Container aktivieren, wird er auch automatisch für den zugrunde liegenden gcsfuse-Prozess aktiviert.

Ersetzen Sie BUCKET_NAME durch den Namen Ihres Cloud Storage-Bucket:

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

Profildaten ansehen

Rufen Sie die Cloud Profiler-Seite in der Google Cloud Console auf, um Ihre Profildaten anzusehen. Verwenden Sie den Filter Dienstname wie folgt, um die Komponente zu analysieren, die Sie untersuchen:

Komponente Filter für Dienstnamen
Knotentreiber gcs-fuse-csi-driver
Sidecar Mounter gke-gcsfuse-sidecar
GCSFuse gcsfuse

Cloud Profiler identifiziert jede Instanz im Format POD_NAME_POD_UID. So wird sichergestellt, dass jede Instanz eindeutig identifiziert wird, auch wenn ein Pod neu gestartet wird.

(Optional) GCSFuse-Profiling deaktivieren

Wenn Sie das Profiling für den Sidecar-Container aktivieren, wird standardmäßig auch der zugrunde liegende gcsfuse-Prozess profiliert. Möglicherweise möchten Sie das gcsfuse-Profiling deaktivieren, um den Ressourcen-Overhead zu reduzieren oder Ihre Analyse ausschließlich auf die Leistung des Sidecar-Containers zu konzentrieren.

Wenn Sie die Profilerstellung für gcsfuse deaktivieren, die Profilerstellung für Sidecars aber aktiviert lassen möchten, fügen Sie enable-cloud-profiler=false dem Attribut mountOptions in der Volumespezifikation hinzu.

Ersetzen Sie BUCKET_NAME durch den Namen Ihres Cloud Storage-Bucket:

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

Logging-Ausführlichkeit konfigurieren

Standardmäßig generiert der Container gke-gcsfuse-sidecar Logs auf den Ebenen info und error. Für das Debugging oder eine detailliertere Analyse müssen Sie jedoch möglicherweise die Ausführlichkeit der Protokollierung anpassen. In diesem Abschnitt wird beschrieben, wie Sie die Logging-Ebene erhöhen oder verringern.

Sie können entweder Bereitstellungsoptionen verwenden, um die Ausführlichkeit der Protokollierung zu konfigurieren, oder die Möglichkeit des CSI-Treibers nutzen, Volume-Attributwerte in die erforderlichen gcsfuse-Konfigurationseinstellungen zu übersetzen.

Fügen Sie im Ziel-Pod-Manifest die folgenden Konfigurationen ein:

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

Wenn Sie die Bereitstellungsoptionen verwenden möchten, fügen Sie dem Ziel-Pod-Manifest die folgende Konfiguration hinzu:

  mountOptions: "logging:severity:LOGGING_SEVERITY"

Ersetzen Sie Folgendes:

  • BUCKET_NAME: Name Ihres Cloud Storage-Buckets.
  • LOGGING_SEVERITY: einer der folgenden Werte, je nach Ihren Anforderungen:
    • trace
    • debug
    • info
    • warning
    • error

Nachdem der Pod bereitgestellt wurde, initiiert der CSI-Treiber gcsfuse mit der neu konfigurierten Logging-Ebene.

Mit dem folgenden Filter können Sie prüfen, ob der Schweregrad der Protokollierung angewendet wird:

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

Probleme beheben

Weitere Informationen zur Fehlerbehebung beim Cloud Storage FUSE-CSI-Treiber finden Sie in der Anleitung zur Fehlerbehebung in der Dokumentation zum GitHub-Projekt.

Nächste Schritte