Leistungsoptimierung mit Cloud Storage FUSE-Profilen automatisieren

In diesem Dokument wird beschrieben, wie Sie die Leistung des Cloud Storage FUSE-CSI-Treibers automatisch optimieren und den Datenzugriff Ihrer KI-/ML-Arbeitslasten mit den Cloud Storage FUSE-Profilen in Google Kubernetes Engine (GKE) beschleunigen können.

Cloud Storage FUSE-Profile automatisieren den kritischen Prozess der Leistungsoptimierung. Anstatt Einstellungen manuell anzupassen, können Sie vordefinierte Profile anwenden, mit denen der CSI-Treiber für Sie konfiguriert wird. Die Verwendung dieser Profile für Ihre KI-/ML-Anwendungen kann zu schnelleren Trainings- und Inferenzzeiten bei geringerem Betriebsaufwand führen.

Dieses Dokument richtet sich an Anwendungsentwickler und Machine Learning-Entwickler, die die Leistung ihrer Anwendungen verbessern möchten, ohne über umfassende Kenntnisse im Bereich Speicheroptimierung zu verfügen. Weitere Informationen zu gängigen Rollen finden Sie unter Häufig verwendete GKE-Nutzerrollen und -Aufgaben.

Bevor Sie dieses Dokument lesen, sollten Sie mit den Grundlagen von Cloud Storage, Kubernetes und dem CSI-Treiber für Cloud Storage FUSE vertraut sein. Lesen Sie auch die Anforderungen für die Verwendung des Cloud Storage FUSE-CSI-Treibers.

Vorteile der Verwendung von Cloud Storage FUSE-Profilen

Um die Leistungsoptimierung für KI‑/ML-Arbeitslasten zu automatisieren, verwenden Cloud Storage FUSE-Profile vordefinierte Cloud Storage FUSE-Konfigurationen und wenden zusätzliche GKE-spezifische Einstellungen an. Diese Einstellungen basieren auf Best Practices für die Leistungsoptimierung von Cloud Storage FUSE. Die Verwendung vordefinierter Profile bietet folgende Vorteile:

  • Vereinfachte Leistungsoptimierung: Verwenden Sie vordefinierte Cloud Storage FUSE-Profile, um die optimierten Konfigurationen für gängige KI/ML-Arbeitslasten wie Training, Bereitstellung und Checkpointing anzuwenden.
  • Dynamische, ressourcenbewusste Optimierung: Mit den Cloud Storage FUSE-Profilen kann der CSI-Treiber die Cachegrößen automatisch anpassen und das optimale Cachemedium wie RAM oder lokale SSD basierend auf Bucket- oder Unterverzeichniseigenschaften wie Größe, Anzahl der Objekte und Standorttyp, Sidecar-Limits und den verfügbaren Ressourcen Ihres Knotens auswählen.
  • Schnellere Leseleistung: Wenn Sie das Profil gcsfusecsi-serving verwenden, aktiviert GKE automatisch Rapid Cache, um die Leseleistung für Ihre Serving-Arbeitslasten zu verbessern.
  • Informationen zur Leistungsoptimierung: Sie erhalten Einblick in die automatisierten Optimierungsentscheidungen über strukturierte Logs, in denen die Eingabesignale aus Ihrer Umgebung und die vom Treiber angewendeten Konfigurationen detailliert beschrieben werden. Weitere Informationen finden Sie unter Statistiken zu Empfehlungen ansehen.

Da sich die Best Practices für Cloud Storage FUSE weiterentwickeln, werden die Profile im Laufe der Zeit durch neue GKE-Releases aktualisiert.

Beschränkungen

Voraussetzungen

Kosten

Zusätzlich zu den Standardkosten für GKE und Cloud Storage, die mit dem CSI-Treiber für Cloud Storage FUSE verbunden sind, fallen bei der Verwendung von Cloud Storage FUSE-Profilen die folgenden Kosten an.

Kosten für das Scannen von Buckets

Bei Cloud Storage FUSE-Profilen wird ein Hintergrundscan Ihres Buckets oder Unterverzeichnisses durchgeführt. Standardmäßig wird dieser Scan alle sieben Tage ausgeführt. Beim Scannen von Buckets fallen Gebühren für Cloud Storage-Vorgänge der Klasse A für das Auflisten von Objekten an.

Kosten für Rapid Cache

Im gcsfusecsi-serving-Profil wird automatisch Rapid Cache aktiviert, das gemäß der Preisgestaltung für Cloud Storage Rapid Cache abgerechnet wird. Informationen dazu, wie Sie Gebühren für Cache-Instanzen vermeiden, wenn diese nicht mehr benötigt werden, finden Sie unter Kostenkontrolle.

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

  • Aktivieren Sie die Cloud Storage API und die Google Kubernetes Engine API.
    • APIs aktivieren
  • Wenn Sie die Google Cloud CLI für diesen Task verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem Befehl gcloud components update ab. In früheren gcloud CLI-Versionen werden die Befehle in diesem Dokument möglicherweise nicht unterstützt.
  • Wählen Sie eine Google Cloud Region aus, die Ihren Anforderungen entspricht. Wir empfehlen zwar, den GKE-Cluster und den Cloud Storage-Bucket in derselben Region zu erstellen, um Leistung und Kosten zu optimieren, aber es ist erforderlich, wenn Sie das gcsfusecsi-serving-Profil verwenden oder Rapid Cache aktivieren möchten.
  • Prüfen Sie, ob Sie einen Cloud Storage-Bucket mit dem Dataset, dem Modell oder den Prüfpunkten für Ihre KI-/ML-Arbeitslast haben. Informationen zum Erstellen eines Buckets finden Sie unter Bucket erstellen.

Leistungsprofil auswählen

Wählen Sie ein Profil aus, das am besten zu Ihrer Arbeitslast passt. Jedes Profil entspricht einer vorinstallierten StorageClass in Ihrem Cluster. Detaillierte Definitionen der Cloud Storage FUSE-Profile finden Sie in der entsprechenden StorageClass-Konfigurationsreferenz.

Profil Name der StorageClass Optimiert für Wichtige Features
Training gcsfusecsi-training Lesevorgänge mit hohem Durchsatz Optimiert die Datenlatenz für GPUs und TPUs während des Trainings mit großen Datasets.
Prüfpunkte gcsfusecsi-checkpointing Schreibvorgänge mit hohem Durchsatz Minimiert die zum Speichern großer Prüfpunkte erforderliche Zeit und verkürzt so Trainingsunterbrechungen.
Bereitstellung gcsfusecsi-serving Datenzugriff und Caching Aktiviert standardmäßig Rapid Cache, um Lesevorgänge zu beschleunigen.

Mit dem folgenden Befehl können Sie die in Ihrem Cluster installierten StorageClasses prüfen:

kubectl get sc -l gke-gcsfuse/profile=true

IAM-Berechtigungen konfigurieren

Gewähren Sie dem GKE-Dienst-Agent Berechtigungen zum Analysieren Ihres Cloud Storage-Bucket und zum Verwalten von Rapid Cache.

Ersetzen Sie die folgenden Platzhalter, wenn Sie die Befehle in diesem Abschnitt ausführen:

  • GCS_PROJECT: Die Projekt-ID, die Ihren Cloud Storage-Bucket enthält.
  • PROJECT_NUMBER: Die Projektnummer Ihres GKE-Clusterprojekts.
  • BUCKET_NAME: Der Name Ihres Cloud Storage-Buckets.

Wählen Sie eine der folgenden Optionen aus, die zu Ihrem Profil und Ihren Nutzungsanforderungen passt.

Option A: Benutzerdefinierte Rolle (empfohlen)

Diese Option ist für das Serving-Profil erforderlich oder wenn Rapid Cache verwendet wird. Wenn Sie das Serving-Profil verwenden oder planen, Rapid Cache für andere Profile manuell zu aktivieren, müssen Sie Berechtigungen zum Verwalten dieses Cache erteilen.

  1. Erstellen Sie eine benutzerdefinierte IAM-Rolle, mit der Objekte gescannt und Rapid Cache-Caches erstellt werden können:

    gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

  2. Binden Sie die benutzerdefinierte Rolle an den GKE-Dienst-Agent für Ihren spezifischen Bucket:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

Option B: Standardrolle für Profile für Training und Checkpointing

Wenn Sie nur die Profile „Training“ oder „Checkpointing“ verwenden und nicht planen, Rapid Cache zu nutzen, führen Sie den folgenden Befehl aus:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Arbeitslast mit einem Cloud Storage FUSE-Profil bereitstellen

So stellen Sie eine Arbeitslast mit einem Cloud Storage FUSE-Profil bereit:

  1. Erstellen Sie ein Manifest für ein PersistentVolume (PV), das auf eine der StorageClasses für das Cloud Storage FUSE-Profil verweist:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

    Ersetzen Sie Folgendes:

    • STORAGECLASS_NAME: Der StorageClass-Name des Profils, das Sie verwenden möchten. Der Wert muss gcsfusecsi-training, gcsfusecsi-checkpointing oder gcsfusecsi-serving sein.
    • BUCKET_DIR_PATH: (optional) Der Pfad in Ihrem Cloud Storage-Bucket, wenn Sie ein bestimmtes Verzeichnis einbinden. Falls angegeben, scannt GKE diesen Pfad nach Optimierungsmöglichkeiten. Wenn nicht angegeben, scannt GKE den gesamten Bucket.
    • BUCKET_NAME: Der Name des Cloud Storage-Bucket, den Sie beim Konfigurieren des Zugriffs auf Cloud Storage-Buckets angegeben haben.

  2. Erstellen Sie einen PersistentVolumeClaim (PVC), der dieselbe StorageClass wie Ihr PV anfordert:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

    Ersetzen Sie Folgendes:

    • NAMESPACE: der Namespace, in dem Sie Ihren Pod bereitstellen möchten.
    • STORAGECLASS_NAME: Der Name der StorageClass, wie in Ihrem PV aufgeführt.

  3. Verwenden Sie das PVC in Ihrem Deployment:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

    Ersetzen Sie Folgendes:

Nach der Bereitstellung berechnet der CSI-Treiber automatisch optimale Cachegrößen und Mount-Optionen basierend auf den Ressourcen Ihres Knotens, z. B. GPUs oder TPUs, Arbeitsspeicher, lokale SSD, die Bucket- oder Unterverzeichnisgröße und die Sidecar-Ressourcenlimits.

Automatisierte Optimierung überprüfen

GKE-Hintergrundprozesse analysieren Ihren Bucket automatisch und synchronisieren Rapid Cache (falls verwendet).

Status des Bucket-Scans und des Cache prüfen

Nachdem Sie die PV erstellt haben, können Sie mit den folgenden Schritten den Status des Bucket-Scans und des Cache prüfen. Sie müssen nicht warten, bis der Pod bereitgestellt wird.

  1. PV-Status prüfen:

    kubectl describe pv my-pv

  2. Prüfen Sie in der Ausgabe, ob das Ereignis ScanOperationSucceeded angezeigt wird. Die entsprechende Ausgabe sieht etwa so aus:

    Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

  3. Wenn Sie das Profil gcsfusecsi-serving verwenden, prüfen Sie, ob das Ereignis AnywhereCacheSyncSucceeded nach dem Laden der Caching-Ebene erfolgt. Die Ausgabe sieht etwa so aus:

    Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running

  4. Prüfen Sie, ob die PV-Anmerkungen mit dem Scanergebnis aktualisiert wurden:

    gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

Pod-Status

Führen Sie nach der Bereitstellung des Pods den folgenden Befehl aus:

kubectl get pods -n NAMESPACE

Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie Ihre Pods bereitgestellt haben.

Ihre Pods sollten jetzt den Status RUNNING haben. Die Best Practices für die Leistung werden automatisch angewendet. Wenn Ihre Pods den Status SchedulingGated haben, bedeutet das, dass GKE Ihren Bucket oder Ihr Unterverzeichnis noch scannt. Die Pods bleiben in diesem Status, bis der CSI-Controller den Scan abgeschlossen und das PV aktualisiert hat.

Informationen zu den spezifischen Optimierungsentscheidungen, die vom Treiber nach dem Start des Pods protokolliert wurden, finden Sie unter Empfehlungen aufrufen.

Sollten Fehler auftreten, lesen Sie den Abschnitt Fehlerbehebung.

StorageClass-Konfigurationsreferenz

In diesem Abschnitt finden Sie die StorageClass-Manifeste für die vorinstallierten Cloud Storage FUSE-Profile sowie eine detaillierte Referenz für die von den Profilen verwendeten Mount-Optionen und ‑Parameter. Mit diesen Konfigurationen kann der gcsfuse.csi.storage.gke.io-Treiber die Leistungsoptimierung und Ressourcenverwaltung für Ihre KI-/ML-Arbeitslasten automatisieren.

Training

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Prüfpunkte

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Bereitstellung

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Die Profile verwenden die folgenden Mount-Optionen und Parameter für den gcsfuse.csi.storage.gke.io-Treiber:

  • mountOptions:
    • profile: Wendet eine vordefinierte Reihe von Cloud Storage FUSE-Optimierungen an, die auf KI-/ML-Arbeitslasten zugeschnitten sind. Die gültigen Werte für die vorinstallierten Profile sind aiml-training, aiml-checkpointing und aiml-serving.
    • read_ahead_kb: Gibt die Größe des Read-Ahead-Puffers in Kilobyte (KB) an. Mit dieser Option kann Cloud Storage FUSE Daten aus Cloud Storage vorab abrufen, was die Leseleistung bei sequenziellen Zugriffsmustern verbessern kann.
    • file-cache:max-size-mb: Gibt für das Serving-Profil die maximale Größe des Dateicache in Mebibyte (MiB) an. Bei Serving-Arbeitslasten, bei denen Modelle in der Regel nur einmal in den GPU- oder TPU-Arbeitsspeicher geladen werden, wird dieser Parameter auf 0 gesetzt, um den lokalen Cloud Storage FUSE-Datei-Cache zu deaktivieren. Dadurch werden redundante Festplatten-E/A-Vorgänge vermieden und lokaler Speicherplatz gespart.
    • read:enable-buffered-read: Für das Serving-Profil ermöglicht diese Option Cloud Storage FUSE, eigene interne Puffer zu verwalten. Dadurch wird die Anzahl der kleinen, teuren Systemaufrufe zwischen der Anwendung und dem Kernel reduziert.
    • read:global-max-blocks: Für das Serving-Profil wird die Gesamtzahl der gleichzeitigen Speicherblöcke begrenzt, die für gepufferte Lesevorgänge verwendet werden. Diese Option verhindert, dass der FUSE-Prozess bei der Verarbeitung mehrerer Anfragen den gesamten verfügbaren RAM belegt.
  • parameters:
    • skipCSIBucketAccessCheck: Wenn der Wert auf "true" gesetzt ist, überspringt der CSI-Treiber die erste Bucket-Zugriffsprüfung. Mit diesem Parameter lassen sich Aufrufe des Security Token Service reduzieren, um potenzielle Probleme mit dem Kontingent zu vermeiden.
    • gcsfuseMetadataPrefetchOnMount: Wenn auf "true" gesetzt, weist der CSI-Treiber an, mit dem prefetching von Objektmetadaten aus Cloud Storage in den lokalen Cache zu beginnen, sobald das Volume bereitgestellt wird. Dieser Parameter kann den ersten Zugriff auf Dateien beschleunigen.
    • fuseFileCacheMediumPriority: Definiert die Prioritätsreihenfolge für Speichermedien, die vom Dateicache von Cloud Storage FUSE verwendet werden. Damit können Sie verschiedene Einstellungen für Knoten mit GPUs, TPUs oder Knoten für allgemeine Zwecke angeben. Zu den Media-Optionen gehören ram und lssd (lokale SSD, falls verfügbar und aktiviert).
    • fuseMemoryAllocatableFactor: Gibt im Stringformat einen Bruchteil an, der den maximalen Arbeitsspeicher begrenzt, den Cloud Storage FUSE-Caches relativ zum gesamten zuweisbaren Arbeitsspeicher des Knotens und zum Arbeitsspeicherlimit des Sidecars belegen können.
    • fuseEphemeralStorageAllocatableFactor: Beschränkt die Verwendung des Cloud Storage FUSE-Caches für sitzungsspezifischen Speicher auf dem Knoten (z. B. lokale SSD für das Datei-Caching) relativ zum zuweisbaren sitzungsspezifischen Speicher des Knotens oder zum sitzungsspezifischen Speicher des Sidecars, der für das Caching begrenzt ist.
    • bucketScanResyncPeriod: Legt das Zeitintervall fest, in dem der PV neu gescannt wird, um Änderungen am Cloud Storage-Bucket zu erkennen.
    • bucketScanTimeout: Die maximal zulässige Dauer für einen einzelnen Bucket-Scanvorgang. Wenn der Scan diese Zeit überschreitet, werden möglicherweise Teilergebnisse verwendet.
    • anywhereCacheZones: Gibt eine durch Kommas getrennte Liste der unterstützten Zonen an, in denen die Rapid Cache-Caches erstellt werden, z. B. "us-central1-a,us-central1-b". Wenn Sie alle für den Cluster verfügbaren Zonen verwenden möchten, geben Sie "*" als Wert an. Wenn Sie diese Option auf "none" setzen oder sie nicht angeben, wird Rapid Cache deaktiviert.
    • anywhereCacheTTL: Die Gültigkeitsdauer (Time To Live, TTL) für Daten, die im Rapid Cache-Cache gespeichert sind, gemessen ab dem letzten Zugriff. Wenn Sie diesen Wert ändern, werden vorhandene Rapid Cache-Instanzen mit dem neuen TTL-Wert aktualisiert.
    • anywhereCacheAdmissionPolicy: Bestimmt, wann Daten nach einem Lesefehler (wenn angeforderte Daten nicht im Cache gefunden werden) in den Rapid Cache aufgenommen werden. Zu den Optionen gehören "admit-on-first-miss", bei der Daten beim ersten Lesefehler aufgenommen werden, und "admit-on-second-miss", bei der Daten nur bei einem zweiten Lesefehler für dasselbe Objekt aufgenommen werden. Wenn Sie diesen Wert ändern, werden vorhandene Rapid Cache-Instanzen mit der neuen Richtlinie aktualisiert.

Optional: Profilkonfigurationen optimieren

Sie können bestimmte Einstellungen in einem Profil anpassen und trotzdem von der Basiskonfiguration profitieren. Mit den folgenden Optionen können Sie ein Profil anpassen, ohne eine neue StorageClass zu erstellen.

Bereitstellungsoptionen und -parameter überschreiben

Wenn Sie bestimmte Verhaltensweisen ändern möchten, fügen Sie dem Feld spec.mountOptions Bereitstellungsoptionen oder dem Feld spec.csi.volumeAttributes CSI-Parameter in Ihrem persistenten Volume hinzu. GKE wendet Ihre manuellen Einstellungen zusätzlich zu den Standardeinstellungen des Profils an.

Im folgenden Beispiel wird gezeigt, wie die Bereitstellungsoption read_ahead_kb überschrieben und der Parameter gcsfuseMetadataPrefetchOnMount im Serving-Profil deaktiviert wird.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

Häufige Anwendungsfälle:

  • Wenn Sie Rapid Cache für ein Trainingsprofil aktivieren möchten, fügen Sie den Parameter anywhereCacheZones direkt in Ihre PV-Spezifikation ein.
  • Um bestimmte Cloud Storage FUSE-Verhaltensweisen anzupassen, z. B. die read_ahead_kb-Größe zu erhöhen, um die spezifischen Anforderungen einer bestimmten Arbeitslast zu erfüllen.

Beachten Sie beim manuellen Konfigurieren von Cachegrößen Folgendes:

  • Wenn Sie eine manuelle Cachegröße angeben, wird die automatische dynamische Größenanpassung nur für diese bestimmte Komponente überschrieben. Die dynamische Größenanpassung wird für alle anderen Komponenten nach dem Best-Effort-Prinzip innerhalb des verbleibenden Ressourcenbudgets fortgesetzt.
  • Wenn Sie eine metadata-cache- oder file-cache-Option wie metadata-cache:stat-cache-max-size-mb festlegen, wird die automatische Berechnung für andere Cachetypen nicht deaktiviert.
  • Wenn Sie file-cache:max-size-mb manuell angeben, müssen Sie auch ein benutzerdefiniertes Volume für den Lesecache konfigurieren. So wird sichergestellt, dass für Ihre benutzerdefinierte Cachegröße ein Speichermedium mit ausreichender Kapazität explizit definiert ist.

Bucket-Scan mit Anmerkungen umgehen

Sie können den automatischen Bucket-Scan umgehen, indem Sie mithilfe von Anmerkungen eigene Messwerte für die Anzahl und Größe von Objekten angeben. Der CSI-Treiber verwendet diese Werte, um optimale Leistungskonfigurationen zu berechnen, ohne den Bucket zu scannen.

Im folgenden Beispiel sehen Sie, wie Sie die Annotation gke-gcsfuse/bucket-scan-status: "override" zusammen mit den spezifischen Messwertannotationen Ihrer PV hinzufügen.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

Häufige Anwendungsfälle:

  • Wenn Sie die Größe und die Anzahl der Objekte Ihres Buckets bereits kennen, insbesondere für Inferenz-Arbeitslasten, bei denen sich Daten selten ändern, können Sie die Scanzeit beim Start umgehen.
  • Wenn die Cloud Storage API vorübergehend nicht verfügbar ist, können Sie mit diesen Anmerkungen die Leistung aufrechterhalten, während die zugrunde liegenden Dienste repariert werden.

Fehlerbehebung

Anhand der folgenden Informationen können Sie den Status von Cloud Storage FUSE-Profilen überwachen und häufige Probleme beheben, die beim Bucket-Scan und bei der Cache-Synchronisierung auftreten.

Ungültiger Konfigurationsparameter (InvalidArgument)

Die Aufgaben zur Hintergrundoptimierung konnten nicht gestartet werden, weil mindestens ein Parameter in Ihrem Manifest ungültig war.

Symptom

In der PV wird ein ScanOperationStartError- oder AnywhereCacheSyncError-Ereignis mit einer Nachricht angezeigt, die rpc error: code = InvalidArgument enthält. Hier einige Beispiele:

  • Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
  • Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

Ursache

Mindestens ein Parameter im Feld spec.csi.volumeAttributes Ihres PV ist falsch formatiert oder enthält Werte, die das System nicht parsen kann.

Lösung

Korrigieren Sie die ungültigen Parameterwerte in Ihrem PV-Manifest und stellen Sie die PV noch einmal bereit. Achten Sie darauf, dass alle Dauerwerte (z. B. bucketScanTimeout) das richtige Format haben (z. B. 2m oder 10m) und dass alle profilspezifischen Einstellungen den gültigen unterstützten Werten entsprechen.

Berechtigung beim Scannen des Cloud Storage-Bucket verweigert

GKE kann nicht auf den angegebenen Cloud Storage-Bucket zugreifen, um die erforderliche Leistungsanalyse durchzuführen.

Symptom

In der PV wird ein ScanOperationStartError-Ereignis mit der Meldung Error 403: Forbidden angezeigt, die darauf hinweist, dass der Aufrufer keinen storage.buckets.get-Zugriff hat.

Ursache

Dem GKE-Dienst-Agent fehlen die erforderlichen IAM-Berechtigungen oder der Bucket-Name ist falsch.

Lösung

  • Prüfen Sie, ob der Bucket-Name im Feld volumeHandle Ihres PV korrekt ist und ob der Bucket vorhanden ist.
  • Prüfen Sie, ob die Berechtigungen des GKE Service Agents für die Identität service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com für den jeweiligen Bucket gewährt wurden. Weitere Informationen finden Sie unter IAM-Berechtigungen konfigurieren.

Rapid Cache-Speicherort stimmt nicht überein

Der Rapid Cache-Cache konnte nicht erstellt werden, da die angeforderte Zone nicht mit dem Standort des Buckets kompatibel ist.

Symptom

In der Vorschau wird ein AnywhereCacheSyncWarning-Ereignis mit der Meldung Invalid zone. Rapid Cache isn't available in the requested zone. angezeigt.

Ursache

Rapid Cache-Caches müssen in Zonen erstellt werden, die sich innerhalb des regionalen Standorts des Buckets befinden. Dieser Fehler tritt in der Regel auf, wenn sich Ihr GKE-Cluster und Ihr Cloud Storage-Bucket in verschiedenen Regionen befinden.

Lösung

Verschieben Sie Ihren Cloud Storage-Bucket in eine Region, die dem Standort Ihres GKE-Cluster entspricht, und stellen Sie das PV neu bereit.

Zeitüberschreitung beim Bucket-Scan

Die Analyse des Cloud Storage-Bucket hat länger als das konfigurierte Zeitlimit gedauert. Daher sind nur teilweise Optimierungsergebnisse verfügbar.

Symptom

Die PV zeigt ein ScanOperationTimedOut-Ereignis. Der Barwert wird mit Teilergebnissen für die Anzahl der Objekte und die Gesamtgröße versehen.

Ursache

Der Bucket enthält eine außergewöhnlich große Anzahl von Objekten (in der Regel mehrere Millionen), die nicht innerhalb des standardmäßigen Zeitlimits von zwei Minuten vollständig aufgelistet werden können.

Lösung

  • Legen Sie im Bereich spec.csi.volumeAttributes Ihrer primären Variablen einen größeren Wert für das Feld bucketScanTimeout fest, z. B. 10m.
  • Wenn die Bucket-Größe statisch ist, können Sie das Scannen umgehen, indem Sie die Anzahl und Größe der Objekte manuell angeben.

Metadaten-Cache durch Arbeitsspeicherbudget begrenzt

Der Treiber hat die Größe des Metadatencaches begrenzt, um die verfügbaren Ressourcen des Knotens nicht zu überschreiten. Das kann die Leistung beeinträchtigen.

Symptom

Die Logs enthalten eine Meldung, dass die erforderliche Größe des Metadaten-Stat-Cache auf das verfügbare Cloud Storage FUSE-Arbeitsspeicherbudget begrenzt wurde.

Ursache

Der Metadatencache für die Anzahl der Objekte in Ihrem Bucket überschreitet den Speicher, der dem Cloud Storage FUSE-Sidecar oder dem verfügbaren Speicher des Knotens zugewiesen ist.

Lösung

  • Verwenden Sie die only-dir-Mount-Option, um das Volume auf ein kleineres Unterverzeichnis mit weniger Objekten zu beschränken.
  • Erhöhen Sie das Speicherlimit für den Cloud Storage FUSE-Sidecar-Container.
    • Wenn die Sidecar-Limits bereits ausreichend sind, verwenden Sie einen Knotentyp mit mehr zuweisbarem Speicher.

Datei-Cache aufgrund von Ressourcenlimits deaktiviert

GKE hat den lokalen Dateicache deaktiviert, da kein geeignetes Speichermedium mit ausreichend Speicherplatz gefunden wurde.

Symptom

In den Logs wird die Warnung No suitable file cache medium found or requirement exceeded limits for all options angezeigt.

Ursache

Die berechnete Dateicachegröße überschreitet sowohl den verfügbaren RAM des Knotens als auch den verfügbaren lokalen SSD-Speicher.

Lösung

  • Verwenden Sie die only-dir-Mount-Option, um das Volume auf ein kleineres Unterverzeichnis mit weniger Objekten zu beschränken.
  • Erhöhen Sie die Ressourcenlimits des Cloud Storage FUSE-Sidecars.
  • Verwenden Sie einen Knotentyp mit mehr Arbeitsspeicher oder aktivieren Sie lokale SSDs in Ihrem Knotenpool.

Status mit PersistentVolume-Ereignissen überwachen

GKE protokolliert wichtige Konfigurationsereignisse und ‑fehler im persistenten Volume. Führen Sie zur Überprüfung dieser Ereignisse den folgenden Befehl aus:

kubectl describe pv PV_NAME

Nachdem der Bucket-Scan erfolgreich abgeschlossen wurde, wird ein ScanOperationSucceeded-Ereignis angezeigt. Wenn Sie das gcsfusecsi-serving-Profil verwenden, wird nach der Aktivierung der Caching-Ebene ein AnywhereCacheSyncSucceeded-Ereignis angezeigt.

Status mithilfe von CSI-Treiberlogs überwachen

Der CSI-Treiber für Cloud Storage FUSE protokolliert detaillierte Konfigurationsentscheidungen und Leistungsinformationen. Verwenden Sie die folgende Abfrage, um diese Logs in Cloud Logging aufzurufen:

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

Empfehlungsstatistiken ansehen

Wenn Sie die spezifischen Eingabesignale und Entscheidungen der automatischen Optimierungslogik nachvollziehen möchten, suchen Sie in den CSI-Treiberlogs nach dem String GCSFuseCSIRecommendation. Die resultierende JSON-Nutzlast enthält detaillierte Messwerte, darunter die folgenden:

  • inputSignals: die Anzahl der Bucket-Objekte, die Gesamtdatengröße und die verfügbaren Knotenressourcen (RAM und temporärer Speicher).
  • decision: Die endgültig berechneten Cache-Größen und das ausgewählte Speichermedium (ram oder lssd).
{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud Konto die in dieser Anleitung erstellten Ressourcen in Rechnung gestellt werden:

  1. Löschen Sie das Deployment:

    kubectl delete deployment my-deployment -n NAMESPACE

    Ersetzen Sie NAMESPACE durch den Kubernetes-Namespace, in dem Sie das Deployment erstellt haben.

  2. Löschen Sie den PersistentVolumeClaim:

    kubectl delete pvc my-pvc -n NAMESPACE

    Ersetzen Sie NAMESPACE durch den Kubernetes-Namespace, in dem Sie den PVC erstellt haben.

  3. Löschen Sie das PersistentVolume:

    kubectl delete pv my-pv

  4. Wenn Sie das gcsfusecsi-serving-Profil verwendet oder Rapid Cache manuell aktiviert haben, folgen Sie der Anleitung unter Cache deaktivieren, um keine Gebühren für Cache-Instanzen mehr zu zahlen.

Nächste Schritte