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

In dieser Anleitung erfahren Sie, wie Sie Ressourcen für den Sidecar-Container des CSI-Treibers für Cloud Storage FUSE konfigurieren, einschließlich der Einrichtung eines privaten Images, eines benutzerdefinierten Schreib-Zwischenspeichers und eines benutzerdefinierten Lese-Cache-Volumes. Normalerweise müssen Sie diese Einstellungen nicht ändern.

Der CSI-Treiber für Cloud Storage FUSE verwendet einen anpassbaren Sidecar-Container, um Cloud Storage-Buckets effizient bereitzustellen und darauf zuzugreifen. Durch die Konfiguration des Sidecar-Containers können Sie die Anwendungsleistung und die Ressourcennutzung optimieren, was zu einem schnelleren Datenzugriff, kürzeren Verarbeitungszeiten und potenziell zu einem geringeren Gesamtresourcenverbrauch für Ihre Anwendung führen kann.

Diese Anleitung richtet sich an Entwickler, Administratoren und Architekten, die die Leistung, Sicherheit und Effizienz ihrer Anwendungen optimieren möchten, die mit GKE interagieren.

Machen Sie sich vor dem Lesen dieser Seite mit den Grundlagen von Cloud Storage, Kubernetes und Containerisierungskonzepten vertraut.

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

Sie können jeden vom 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-Cache 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. Mit 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 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: der Name des vordefinierten PVC.

Benutzerdefiniertes Lese-Cache-Volume konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Cache-Volume für das Lese-Caching 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 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. Mit 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 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: 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: 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 also 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. Die detaillierten Daten können Ihnen helfen, die CPU- und Arbeitsspeichernutzung im CSI-Treiber für Cloud Storage FUSE und im zugehörigen Sidecar-Container proaktiv zu beobachten. 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 für Administratoren gedacht, 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 die 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, authentifiziert er sich mit dem IAM-Dienstkonto, das dem GKE-Knoten zugeordnet ist, anstatt Workload Identity Federation for GKE zu verwenden.

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 Compute Engine-Standarddienstkonto, 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 authentifizieren sich mit Workload Identity Federation for GKE, die das Kubernetes-Dienstkonto (Kubernetes Service Account, KSA) verwendet, das Ihrem Arbeitslast-Pod zugeordnet 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 den Sidecar-Mounter und den zugrunde liegenden gcsfuse Prozess generieren möchten, setzen Sie das enableCloudProfilerForSidecar Volume-Attribut in Ihrer Arbeitslastspezifikation auf "true". 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-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-Profilerstellung deaktivieren

Standardmäßig wird beim Aktivieren der Profilerstellung für den Sidecar-Container 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 in Ihrer Volume-Spezifikation enable-cloud-profiler=false zum Attribut 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 Protokollebene erhöhen oder verringern.

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

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

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

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

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

Mit dem folgenden Filter können Sie prüfen, ob die Protokollebene 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 der Anleitung zur Fehlerbehebung in der Dokumentation zum GitHub-Projekt.

Nächste Schritte