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 CSI-Treibers für Cloud Storage FUSE in Google Kubernetes Engine (GKE) konfigurieren.

Konfigurieren Sie bestimmte Ressourceneinstellungen für den Sidecar-Container des CSI-Treibers für Cloud Storage FUSE, um die Leistung und Ressourcennutzung Ihrer Anwendung in GKE zu optimieren. Wenn Sie diese Ressourcen einrichten, z. B. ein privates Image, einen benutzerdefinierten Schreibpuffer und ein benutzerdefiniertes Lesecache-Volume, haben Sie mehr Kontrolle darüber, wie Ihre Anwendungen mit Cloud Storage interagieren. Diese Konfigurationen können zu einem schnelleren Datenzugriff, kürzeren Verarbeitungszeiten und möglicherweise zu einem geringeren Ressourcenverbrauch in Ihren GKE-Clustern führen.

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.

Machen Sie sich mit den folgenden Konzepten zu Arbeitslasten und Speicher vertraut, bevor Sie beginnen:

Funktionsweise des Sidecar-Containers

Der CSI-Treiber für Cloud Storage FUSE 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 gke-gcsfuse/volumes: "true" Annotation in einer Pod-Spezifikation erkennt, fügt er automatisch den Sidecar-Container ein. Dieser Ansatz mit Sidecar-Containern 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-Container-Modell sorgt auch dafür, dass die Cloud Storage FUSE-Instanz an den Lebenszyklus der Arbeitslast gebunden ist, sodass sie nicht unnötig Ressourcen verbraucht. Das bedeutet, dass der Sidecar-Container automatisch beendet wird, wenn die Arbeitslastcontainer beendet werden, insbesondere bei Arbeitslasten vom Typ „Job“ oder Pods mit einer RestartPolicy von Never.

Kompatibilität mit Cloud Service Mesh und OSS Istio

Der Sidecar-Container des CSI-Treibers für Cloud Storage FUSE 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. Diese Annotation konfiguriert Istio oder Cloud Service Mesh so, dass die IP-Adresse des GKE-Metadatenservers von der Umleitung ausgeschlossen wird.

Benutzerdefinierten Schreibpuffer 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 bei Schreibvorgängen bereitzustellen. Das ist nützlich, wenn Sie in Autopilot-Clustern Dateien schreiben müssen, die größer als 10 GiB sind.

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

Wenn Sie ein benutzerdefiniertes Zwischenspeicher-Volume verwenden möchten, das von einem nichtflüchtigen Speicher unterstützt wird, müssen Sie in der securityContext Ihres Pods einen Wert für fsGroup angeben, der nicht null ist. Dadurch 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 mit dem CSI-Treiber für Cloud Storage FUSE als nichtflüchtige Volumes bereitstellt.

Das folgende Beispiel zeigt, wie Sie einen vordefinierten PersistentVolumeClaim als Zwischenspeicher-Volume 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 dabei Folgendes:

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

Benutzerdefiniertes Lesecache-Volume konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Cache-Volume für das Lesecaching 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 bei Lesevorgängen zu cachen. Sie können jeden von GKE unterstützten Speichertyp angeben, z. B. einen PersistentVolumeClaim. GKE verwendet das angegebene Volume für das Datei-Caching. Das ist nützlich, wenn Sie in Autopilot-Clustern Dateien cachen müssen, die größer als 10 GiB sind.

Wenn Sie ein benutzerdefiniertes Cache-Volume verwenden möchten, das von einem nichtflüchtigen Speicher unterstützt wird, müssen Sie in der securityContext Ihres Pods einen Wert für fsGroup angeben, der nicht null ist. Dadurch 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 mit dem CSI-Treiber für Cloud Storage FUSE als nichtflüchtige Volumes bereitstellt.

Das folgende Beispiel zeigt, 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 dabei 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 an, der nur das Feld „Image“ enthält. 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.

Ressourcen für den Sidecar-Container konfigurieren

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

Anfragen:

  • 250m CPU
  • 256 MiB Arbeitsspeicher
  • 5 GiB sitzungsspezifischer Speicher

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

  • Unbegrenzte CPU
  • Unbegrenzter Arbeitsspeicher
  • Unbegrenzter sitzungsspezifischer Speicher

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

  • 250m CPU
  • 256 MiB Arbeitsspeicher
  • 5 GiB sitzungsspezifischer Speicher

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

Anfragen:

  • 10m CPU
  • 10 MiB Arbeitsspeicher
  • 10 MiB sitzungsspezifischer Speicher

Limits:

  • 50m CPU
  • 250 MiB Arbeitsspeicher
  • Unbegrenzter sitzungsspezifischer Speicher

In Standard- und Autopilot-Clustern können Sie die Standardwerte überschreiben. Wie GKE mit Containerressourcen umgeht, hängt vom Clustermodus ab:

  • Standard-Cluster: Wenn eine der Anfragen oder Limits festgelegt und eine andere nicht festgelegt ist, werden die Ressourcenlimits und -anfragen der Pods gleich festgelegt. Wenn sowohl Anfragen als auch Limits festgelegt sind, verwenden Pods die genauen Ressourcenanfragen und -limits, die Sie angeben. 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 gleich 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 Container gke-gcsfuse-metadata-prefetch überschreiben möchten (ab GKE-Version 1.32.3-gke.1717000), 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

Sie können den Wert "0" verwenden, um alle Ressourcenlimits oder -anfragen aufzuheben. Beachten Sie jedoch, dass der gke-gcsfuse-sidecar Container bereits alle Limits (cpu-limit, memory-limit und ephemeral-storage-limit) aufgehoben hat und der gke-gcsfuse-metadata-prefetch Container bereits ephemeral-storage-limit aufgehoben hat. Wenn Sie diese Limits in einem Cluster mit GKE-Version 1.32.3-gke.1717000 oder höher auf "0" setzen, hat das keine Auswirkungen.

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

(Optional) Leistung mit Cloud Profiler analysieren

Mit Cloud Profiler erhalten Sie kontinuierlich detaillierte Einblicke in den Ressourcenverbrauch Ihrer speicherintensiven Anwendungen. Mit den detaillierten Daten können Sie die CPU- und Arbeitsspeichernutzung im CSI-Treiber für Cloud Storage FUSE und im zugehörigen Sidecar-Container proaktiv überwachen. Die Erkenntnisse aus den Cloud Profiler-Daten können Ihnen helfen, ineffiziente Codepfade zu identifizieren, die Ressourcenzuweisung zu optimieren und komplexe Probleme wie Speicherlecks oder unerwartete Ereignisse vom Typ „Out of Memory“ (OOM) zu beheben, bevor sie sich auf die Dienststabilität auswirken.

Die Verwendung von Cloud Profiler ist optional und richtet sich an Administratoren, die eine detaillierte Leistungsdiagnose 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.

Vorbereitung für die Aktivierung von Cloud Profiler

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

API aktivieren

Cloud Profiler API aktivieren

Berechtigungen für den Knotentreiber erteilen

Zum Senden von Profildaten an Cloud Profiler benötigt der Knotentreiber IAM-Berechtigungen. Da der Knotentreiber standardmäßig im Hostnetzwerk ausgeführt wird, erfolgt die Authentifizierung mit dem IAM-Dienstkonto, das mit dem GKE-Knoten verknüpft ist, und nicht mit der Identitätsföderation von Arbeitslasten 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 dabei Folgendes:

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

Berechtigungen für den Sidecar-Container erteilen

Zum Senden von Profildaten an Cloud Profiler benötigen der Sidecar-Container und der gcsfuse-Prozess IAM-Berechtigungen. Diese Komponenten werden mit der Identitätsföderation von Arbeitslasten für GKE authentifiziert, die das Kubernetes-Dienstkonto (KSA) verwendet, das mit Ihrem Arbeitslast-Pod verknüpft ist.

Weisen Sie dem KSA, das Ihr Pod verwendet, 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 dabei Folgendes:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID.
  • PROJECT_NUMBER: die Projektnummer von Google Cloud PROJECT_ID.
  • 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 die Sidecar-Bereitstellung und den zugrunde liegenden gcsfuse Prozess generieren möchten, legen Sie das Volume-Attribut enableCloudProfilerForSidecar in Ihrer Arbeitslastspezifikation auf "true" fest. Wenn Sie Cloud Profiler für den Sidecar-Container aktivieren, wird es 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

Wenn Sie Ihre Profildaten ansehen möchten, rufen Sie in der Google Cloud Console die Seite „Cloud Profiler“ auf. Verwenden Sie den Filter Dienstname wie folgt, um die zu untersuchende Komponente zu analysieren:

Komponente Filter für Dienstname
Knotentreiber gcs-fuse-csi-driver
Sidecar-Bereitstellung 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-Profilerstellung deaktivieren

Wenn Sie die Profilerstellung für den Sidecar-Container aktivieren, wird standardmäßig auch der zugrunde liegende gcsfuse-Prozess profiliert. Sie können die gcsfuse-Profilerstellung deaktivieren, um den Ressourcenaufwand zu reduzieren oder Ihre Analyse ausschließlich auf die Leistung des Sidecar-Containers zu konzentrieren.

Wenn Sie die gcsfuse-Profilerstellung deaktivieren, aber die Sidecar-Profilerstellung aktiviert lassen möchten, fügen Sie der Volume-Spezifikation das Attribut enable-cloud-profiler=false zu mountOptions 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"

Ausführlichkeit der Logs 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 Logs anpassen. In diesem Abschnitt wird beschrieben, wie Sie die Logebene erhöhen oder verringern.

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

Fügen Sie dem Manifest des Ziel-Pods die folgenden Konfigurationen hinzu:

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

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

  mountOptions: "logging:severity:LOGGING_SEVERITY"

Ersetzen Sie dabei Folgendes:

  • BUCKET_NAME: Name Ihres Cloud Storage-Bucket.
  • 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 Logebene.

Mit dem folgenden Filter können Sie prüfen, ob die Logebene angewendet wurde:

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 CSI-Treiber für Cloud Storage FUSE finden Sie unter dem Leitfaden zur Fehlerbehebung in der Dokumentation zum GitHub-Projekt.

Nächste Schritte