Automatizza l'ottimizzazione delle prestazioni con i profili Cloud Storage FUSE

Questo documento descrive come ottimizzare automaticamente le prestazioni del driver CSI di Cloud Storage FUSE e accelerare l'accesso ai dati dei tuoi workload AI/ML utilizzando i profili Cloud Storage FUSE su Google Kubernetes Engine (GKE).

I profili Cloud Storage FUSE automatizzano il processo critico di ottimizzazione delle prestazioni. Invece di modificare manualmente le impostazioni, puoi applicare profili predefiniti che configurano il driver CSI per te. Per le tue applicazioni AI/ML, l'utilizzo di questi profili può portare a tempi di addestramento e inferenza più rapidi con un overhead operativo ridotto.

Questo documento è destinato a sviluppatori di applicazioni e ingegneri di machine learning (ML) che vogliono migliorare le prestazioni delle loro applicazioni senza competenze approfondite di ottimizzazione dello spazio di archiviazione. Per scoprire di più sui ruoli comuni, consulta Ruoli utente e attività comuni di GKE.

Prima di leggere questo documento, assicurati di conoscere le nozioni di base di Cloud Storage, Kubernetes e del driver CSI di Cloud Storage FUSE. Inoltre, esamina i requisiti per l'utilizzo del driver CSI di Cloud Storage FUSE.

Vantaggi dell'utilizzo dei profili Cloud Storage FUSE

Per automatizzare l'ottimizzazione delle prestazioni per i carichi di lavoro AI/ML, i profili Cloud Storage FUSE utilizzano configurazioni Cloud Storage FUSE predefinite e applicano impostazioni aggiuntive specifiche di GKE. Queste impostazioni si basano sulle best practice di ottimizzazione delle prestazioni di Cloud Storage FUSE. L'utilizzo di profili predefiniti offre i seguenti vantaggi:

  • Ottimizzazione semplificata delle prestazioni: utilizza profili Cloud Storage FUSE predefiniti per applicare le configurazioni ottimizzate per i workload AI/ML comuni, come training, serving e checkpoint.
  • Ottimizzazione dinamica e consapevole delle risorse: l'utilizzo dei profili Cloud Storage FUSE consente al driver CSI di regolare automaticamente le dimensioni della cache e selezionare il mezzo di memorizzazione nella cache ottimale, ad esempio RAM o SSD locale, in base alle caratteristiche del bucket o della sottodirectory, come dimensioni, numero di oggetti e tipo di posizione, limiti dei file collaterali e risorse disponibili del nodo.
  • Prestazioni di lettura accelerate: quando utilizzi il profilo gcsfusecsi-serving, GKE abilita automaticamente Rapid Cache per migliorare le prestazioni di lettura per i tuoi carichi di lavoro di pubblicazione.
  • Approfondimenti sull'ottimizzazione del rendimento: ottieni informazioni sulle decisioni di ottimizzazione automatica tramite log strutturati che descrivono in dettaglio gli indicatori di input del tuo ambiente e le configurazioni risultanti applicate dal driver. Per saperne di più, consulta Visualizzare gli approfondimenti sui consigli.

Man mano che le best practice di Cloud Storage FUSE si evolvono, i profili vengono aggiornati nel tempo tramite le nuove release di GKE.

Limitazioni

Requisiti

Costi

Oltre ai costi standard di GKE e Cloud Storage associati al driver CSI di Cloud Storage FUSE, l'utilizzo dei profili Cloud Storage FUSE comporta i seguenti costi.

Costi di scansione dei bucket

I profili Cloud Storage FUSE eseguono una scansione in background del bucket o della sottodirectory. Per impostazione predefinita, questa scansione viene eseguita ogni sette giorni. La scansione dei bucket comporta costi per le operazioni di classe A di Cloud Storage per l'elenco degli oggetti.

Costi di Rapid Cache

Il profilo gcsfusecsi-serving attiva automaticamente Rapid Cache, che viene fatturato in base ai prezzi di Cloud Storage Rapid Cache. Per evitare di sostenere addebiti per le istanze della cache quando non sono più necessarie, consulta Controlli dei costi.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

  • Attiva l'API Cloud Storage e l'API Google Kubernetes Engine.
    • Abilita le API
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.
  • Scegli una Google Cloud regione adatta alle tue esigenze. Sebbene consigliamo di creare il cluster GKE e il bucket Cloud Storage nella stessa regione per ottimizzare le prestazioni e i costi, è obbligatorio farlo quando utilizzi il profilo gcsfusecsi-serving o prevedi di attivare Rapid Cache.
  • Assicurati di avere un bucket Cloud Storage esistente contenente il set di dati, il modello o i checkpoint per il tuo carico di lavoro AI/ML. Se devi creare un bucket, consulta Crea un bucket.

Seleziona un profilo delle prestazioni

Scegli un profilo che corrisponda al meglio al tuo workload. Ogni profilo corrisponde a una StorageClass preinstallata sul cluster. Per definizioni dettagliate dei profili FUSE di Cloud Storage, consulta il riferimento alla configurazione di StorageClass corrispondente.

Profilo Nome StorageClass Ottimizzato per Funzionalità principali
Formazione gcsfusecsi-training Letture ad alta velocità effettiva Ottimizza la latenza dei dati per GPU e TPU durante l'addestramento su set di dati di grandi dimensioni.
Checkpoint gcsfusecsi-checkpointing Scritture con velocità effettiva elevata Riduce al minimo il tempo necessario per salvare checkpoint di grandi dimensioni, riducendo le pause di addestramento.
Pubblicazione gcsfusecsi-serving Accesso ai dati e memorizzazione nella cache Abilita Rapid Cache per impostazione predefinita per accelerare le operazioni di lettura.

Puoi verificare le StorageClass installate nel cluster eseguendo il comando seguente:

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

Configurare le autorizzazioni IAM

Concedi le autorizzazioni service agent GKE per analizzare il bucket Cloud Storage e gestire Rapid Cache.

Sostituisci i seguenti segnaposto quando esegui i comandi in questa sezione:

  • GCS_PROJECT: l'ID progetto contenente il bucket Cloud Storage.
  • PROJECT_NUMBER: il numero del progetto del cluster GKE.
  • BUCKET_NAME: il nome del bucket Cloud Storage.

Scegli una delle seguenti opzioni in base al tuo profilo e alle tue esigenze di utilizzo.

Opzione A: ruolo personalizzato (consigliata)

Questa opzione è obbligatoria per il profilo Serving o se viene utilizzato Rapid Cache. Se utilizzi il profilo di pubblicazione o prevedi di attivare manualmente Rapid Cache per altri profili, devi concedere le autorizzazioni per gestire la cache.

  1. Crea un ruolo IAM personalizzato che consenta di eseguire la scansione degli oggetti e creare cache Rapid Cache:

    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. Associa il ruolo personalizzato al service agent GKE per il tuo bucket specifico:

    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"

Opzione B: ruolo standard per i profili di addestramento e checkpoint

Se utilizzi solo i profili Training o Checkpointing e non prevedi di utilizzare Rapid Cache, esegui questo comando:

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"

Esegui il deployment di un carico di lavoro con un profilo Cloud Storage FUSE

Segui questi passaggi per eseguire il deployment di un carico di lavoro con un profilo Cloud Storage FUSE.

  1. Crea un manifest PersistentVolume (PV) che faccia riferimento a una delle StorageClass del profilo Cloud Storage FUSE:

    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

    Sostituisci quanto segue:

    • STORAGECLASS_NAME: il nome StorageClass del profilo che vuoi utilizzare. Il valore deve essere gcsfusecsi-training, gcsfusecsi-checkpointing o gcsfusecsi-serving.
    • BUCKET_DIR_PATH: (facoltativo) il percorso all'interno del bucket Cloud Storage, se stai montando una directory specifica. Se specificato, GKE esegue la scansione di questo percorso per l'ottimizzazione. Se omesso, GKE esegue la scansione dell'intero bucket.
    • BUCKET_NAME: il nome del bucket Cloud Storage che hai specificato durante la configurazione dell'accesso ai bucket Cloud Storage.

  2. Crea un PersistentVolumeClaim (PVC) che richieda la stessa StorageClass del tuo PV:

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

    Sostituisci quanto segue:

    • NAMESPACE: lo spazio dei nomi in cui vuoi eseguire il deployment del pod.
    • STORAGECLASS_NAME: il nome di StorageClass come elencato nel PV.

  3. Utilizza il PVC nel 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

    Sostituisci quanto segue:

Una volta distribuito, il driver CSI calcola automaticamente le dimensioni ottimali della cache e le opzioni di montaggio in base alle risorse del nodo, come GPU o TPU, memoria, SSD locale, dimensioni del bucket o della sottodirectory e limiti delle risorse sidecar.

Verificare l'ottimizzazione automatica

I processi in background di GKE analizzano automaticamente il bucket e sincronizzano Rapid Cache (se in uso).

Controlla lo stato della scansione del bucket e della cache

Dopo aver creato la PV, segui questi passaggi per controllare lo stato sia della scansione del bucket sia della cache. Non devi attendere il deployment del pod.

  1. Controlla lo stato del PV:

    kubectl describe pv my-pv

  2. Nell'output, verifica che venga visualizzato l'evento ScanOperationSucceeded. L'output è simile al seguente:

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

  3. Se utilizzi il profilo gcsfusecsi-serving, verifica che l'evento AnywhereCacheSyncSucceeded venga visualizzato dopo che il livello di memorizzazione nella cache è pronto. L'output è simile al seguente:

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

  4. Verifica che le annotazioni PV siano aggiornate con il risultato della scansione:

    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

Controllare lo stato del pod

Dopo aver eseguito il deployment del pod, esegui questo comando:

kubectl get pods -n NAMESPACE

Sostituisci NAMESPACE con lo spazio dei nomi in cui hai eseguito il deployment dei pod.

I tuoi pod ora dovrebbero essere in stato RUNNING, con le best practice per il rendimento applicate automaticamente. Se i pod mostrano lo stato SchedulingGated, significa che GKE sta ancora analizzando il bucket o la sottodirectory. I pod rimangono in questo stato finché il controller CSI non completa la scansione e aggiorna il PV.

Per comprendere le decisioni di ottimizzazione specifiche registrate dal conducente dopo l'avvio del Pod, consulta Visualizzare gli approfondimenti sui consigli.

Se riscontri errori, consulta la sezione Risoluzione dei problemi.

Riferimento alla configurazione di StorageClass

Questa sezione fornisce i manifest StorageClass per i profili Cloud Storage FUSE preinstallati e un riferimento dettagliato per le opzioni di montaggio e i parametri utilizzati dai profili. Queste configurazioni consentono al driver gcsfuse.csi.storage.gke.io di automatizzare la regolazione delle prestazioni e la gestione delle risorse per i tuoi workload AI/ML.

Formazione

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"

Checkpoint

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"

Pubblicazione

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"

I profili utilizzano le seguenti opzioni di montaggio e parametri per il driver gcsfuse.csi.storage.gke.io:

  • mountOptions:
    • profile: applica un insieme predefinito di ottimizzazioni di Cloud Storage FUSE personalizzate per i carichi di lavoro AI/ML. I valori validi per i profili preinstallati sono aiml-training, aiml-checkpointing e aiml-serving.
    • read_ahead_kb: specifica le dimensioni del buffer di lettura anticipata in kilobyte (KB). Questa opzione consente a Cloud Storage FUSE di eseguire il prefetch dei dati da Cloud Storage, migliorando potenzialmente le prestazioni di lettura per pattern di accesso sequenziali.
    • file-cache:max-size-mb: per il profilo di pubblicazione, specifica le dimensioni massime in mebibyte (MiB) per la cache dei file. Nel servizio dei carichi di lavoro, in cui i modelli vengono in genere caricati nella memoria della GPU o della TPU una sola volta, questo parametro è impostato su 0 per disattivare la cache dei file di Cloud Storage FUSE locale, il che contribuisce a evitare I/O del disco ridondanti e a risparmiare spazio di archiviazione locale.
    • read:enable-buffered-read: per il profilo di pubblicazione, consente a Cloud Storage FUSE di gestire i propri buffer interni, il che contribuisce a ridurre il numero di chiamate di sistema piccole e costose tra l'applicazione e il kernel.
    • read:global-max-blocks: per il profilo di pubblicazione, limita il numero totale di blocchi di memoria simultanei utilizzati per le letture bufferizzate. Questa opzione consente di impedire al processo FUSE di consumare tutta la RAM disponibile durante la gestione di più richieste.
  • parameters:
    • skipCSIBucketAccessCheck: se impostato su "true", il driver CSI salta il controllo iniziale dell'accesso al bucket. Questo parametro consente di ridurre le chiamate al Security Token Service per evitare potenziali problemi di quota.
    • gcsfuseMetadataPrefetchOnMount: se impostato su "true", indica al driver CSI di avviare il prefetching dei metadati degli oggetti da Cloud Storage nella cache locale non appena viene montato il volume. Questo parametro può accelerare il primo accesso ai file.
    • fuseFileCacheMediumPriority: definisce l'ordine di priorità per i supporti di archiviazione utilizzati dalla cache dei file di Cloud Storage FUSE. Consente di specificare preferenze diverse per i nodi con GPU, TPU o per i nodi per uso generico. Le opzioni multimediali includono ram e lssd (SSD locale, se disponibile e abilitato).
    • fuseMemoryAllocatableFactor: specifica in formato stringa una frazione che limita la memoria massima che le cache di Cloud Storage FUSE possono consumare, rispetto alla memoria allocabile totale del nodo e al limite di memoria del sidecar.
    • fuseEphemeralStorageAllocatableFactor: limita l'utilizzo della cache Cloud Storage FUSE dello spazio di archiviazione temporanea sul nodo (ad esempio SSD locale per la memorizzazione nella cache dei file), rispetto allo spazio di archiviazione temporanea allocabile del nodo o allo spazio di archiviazione temporanea del sidecar limitato per la memorizzazione nella cache.
    • bucketScanResyncPeriod: imposta l'intervallo di tempo in cui viene eseguita nuovamente la scansione del PV per rilevare le modifiche apportate al bucket Cloud Storage.
    • bucketScanTimeout: la durata massima consentita per una singola operazione di scansione del bucket. Se la scansione supera questo tempo, potrebbero essere utilizzati risultati parziali.
    • anywhereCacheZones: specifica un elenco separato da virgole di zone supportate in cui vengono create le cache Rapid Cache, ad esempio "us-central1-a,us-central1-b". Per utilizzare tutte le zone disponibili per il cluster, utilizza "*" come valore. Se questa impostazione viene impostata su "none" o non viene specificata, Rapid Cache viene disattivata.
    • anywhereCacheTTL: la durata (TTL) dei dati memorizzati nella cache Rapid Cache, misurata dall'ultimo accesso. Se modifiche questo valore, le istanze Rapid Cache esistenti vengono aggiornate con il nuovo TTL.
    • anywhereCacheAdmissionPolicy: determina quando inserire i dati nella Rapid Cache dopo un errore di lettura (quando i dati richiesti non vengono trovati nella cache). Le opzioni includono "admit-on-first-miss", che ammette i dati al primo errore di lettura, oppure "admit-on-second-miss", che ammette i dati solo al secondo errore di lettura per lo stesso oggetto. Se modifichi questo valore, le istanze Rapid Cache esistenti vengono aggiornate con il nuovo criterio.

(Facoltativo) Perfeziona le configurazioni dei profili

Puoi personalizzare impostazioni specifiche in un profilo, beneficiando comunque della sua configurazione di base. Utilizza le seguenti opzioni per modificare un profilo senza creare una nuova StorageClass.

Eseguire l'override delle opzioni e dei parametri di montaggio

Per modificare comportamenti specifici, aggiungi opzioni di montaggio al campo spec.mountOptions o parametri CSI al campo spec.csi.volumeAttributes nel PV. GKE applica le impostazioni manuali in aggiunta a quelle predefinite del profilo.

L'esempio seguente mostra come eseguire l'override dell'opzione di montaggio read_ahead_kb e disattivare il parametro gcsfuseMetadataPrefetchOnMount nel profilo di pubblicazione.

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.

I casi d'uso comuni includono:

  • Per attivare Rapid Cache per un profilo Training, aggiungi il parametro anywhereCacheZones direttamente alla specifica PV.
  • Per modificare comportamenti specifici di Cloud Storage FUSE, ad esempio aumentare le dimensioni di read_ahead_kb, per soddisfare i requisiti unici di un particolare workload.

Quando configuri manualmente le dimensioni della cache, tieni presente quanto segue:

  • La specifica di una dimensione della cache manuale sostituisce il dimensionamento dinamico automatico solo per quel componente specifico. Il dimensionamento dinamico continua per tutti gli altri componenti in base al massimo impegno possibile all'interno del budget delle risorse rimanente.
  • L'impostazione di un'opzione metadata-cache o file-cache, ad esempio metadata-cache:stat-cache-max-size-mb, non disattiva il calcolo automatico per altri tipi di cache.
  • Se specifichi manualmente file-cache:max-size-mb, devi anche configurare un volume della cache di lettura personalizzato. Ciò contribuisce a garantire che un supporto di archiviazione con capacità sufficiente sia definito in modo esplicito per le dimensioni della cache personalizzata.

Ignorare la scansione dei bucket con le annotazioni

Puoi ignorare il processo di scansione automatica dei bucket fornendo le tue metriche relative al conteggio e alle dimensioni degli oggetti utilizzando le annotazioni. Il driver CSI utilizza questi valori per calcolare le configurazioni di rendimento ottimali senza eseguire la scansione del bucket.

L'esempio seguente mostra come aggiungere l'annotazione gke-gcsfuse/bucket-scan-status: "override" alla visualizzazione di pagina, insieme alle annotazioni delle metriche specifiche.

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

I casi d'uso comuni includono:

  • Se conosci già le dimensioni e il conteggio degli oggetti del bucket, soprattutto per i carichi di lavoro di inferenza in cui i dati cambiano raramente, puoi ignorare la scansione all'avvio.
  • Se l'API Storage Cloud non è temporaneamente disponibile, queste annotazioni possono aiutarti a mantenere le prestazioni mentre i servizi sottostanti vengono corretti.

Risoluzione dei problemi

Utilizza le seguenti informazioni per monitorare lo stato dei profili Cloud Storage FUSE e risolvere i problemi comuni riscontrati durante la scansione dei bucket e la sincronizzazione della cache.

Parametro di configurazione non valido (InvalidArgument)

Le attività di ottimizzazione in background non sono state avviate perché uno o più parametri forniti nel manifest non erano validi.

Sintomo

Il PV mostra un evento ScanOperationStartError o AnywhereCacheSyncError con un messaggio contenente rpc error: code = InvalidArgument. Ecco alcuni esempi:

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

Causa

Uno o più parametri nel campo spec.csi.volumeAttributes della tua PV sono formattati in modo errato o contengono valori che il sistema non può analizzare.

Risoluzione

Correggi i valori dei parametri non validi nel file manifest del PV e implementa nuovamente il PV. Assicurati che tutti i valori di durata (ad es. bucketScanTimeout) utilizzino il formato corretto (ad es. 2m o 10m) e che tutte le impostazioni specifiche del profilo corrispondano ai valori supportati validi.

Autorizzazione negata durante la scansione del bucket Cloud Storage

GKE non può accedere al bucket Cloud Storage specificato per eseguire l'analisi delle prestazioni richiesta.

Sintomo

Il PV mostra un evento ScanOperationStartError con un messaggio Error 403: Forbidden che indica che il chiamante non dispone dell'accesso storage.buckets.get.

Causa

L'agente di servizio GKE non dispone delle autorizzazioni IAM necessarie o il nome del bucket non è corretto.

Risoluzione

  • Verifica che il nome del bucket nel campo volumeHandle della tua PV sia corretto e che il bucket esista.
  • Assicurati che le autorizzazioni dell'agente di servizio GKE siano concesse all'identità service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com per il bucket specifico. Per saperne di più, consulta Configurare le autorizzazioni IAM.

Posizione di Rapid Cache non corrispondente

Impossibile creare la cache Rapid Cache perché la zona richiesta non è compatibile con la località del bucket.

Sintomo

Il PV mostra un evento AnywhereCacheSyncWarning con il messaggio: Invalid zone. Rapid Cache isn't available in the requested zone.

Causa

Le cache Rapid Cache devono essere create in zone che si trovano all'interno della località regionale del bucket. Questo errore si verifica in genere quando il cluster GKE e il bucket Cloud Storage si trovano in regioni diverse.

Risoluzione

Sposta il bucket Cloud Storage in una regione che corrisponda alla località del cluster GKE ed esegui nuovamente il deployment del PV.

Scansione del bucket scaduta

L'analisi del bucket Cloud Storage ha richiesto più tempo del timeout configurato, con conseguenti risultati di ottimizzazione parziali.

Sintomo

Il PV mostra un evento ScanOperationTimedOut. Il PV è annotato con risultati parziali per il conteggio degli oggetti e le dimensioni totali.

Causa

Il bucket contiene un numero eccezionalmente elevato di oggetti (in genere diversi milioni) che non possono essere elencati completamente entro il timeout predefinito di due minuti.

Risoluzione

  • Imposta un valore maggiore per il campo bucketScanTimeout nella sezione spec.csi.volumeAttributes del PV, ad esempio 10m.
  • Se le dimensioni del bucket sono statiche, ignora la scansione fornendo manualmente il conteggio e le dimensioni degli oggetti.

Cache dei metadati limitata dal budget di memoria

Il driver ha limitato le dimensioni della cache dei metadati per adattarsi alle risorse disponibili del nodo, il che potrebbe ridurre le prestazioni.

Sintomo

I log contengono un messaggio che indica che la dimensione della cache delle statistiche dei metadati richiesta è stata limitata al budget di memoria di Cloud Storage FUSE disponibile.

Causa

La cache dei metadati per il numero di oggetti nel bucket supera la memoria allocata al sidecar Cloud Storage FUSE o la memoria disponibile del nodo.

Risoluzione

  • Utilizza l'opzione di montaggio only-dir per limitare il volume a una sottodirectory più piccola con meno oggetti.
  • Aumenta il limite di memoria per il container sidecar Cloud Storage FUSE.
    • Se i limiti dei sidecar sono già sufficienti, utilizza un tipo di nodo con più memoria allocabile.

Cache dei file disattivata a causa dei limiti delle risorse

GKE ha disattivato la cache dei file locali perché non è stato possibile trovare un supporto di archiviazione adatto con spazio sufficiente.

Sintomo

I log mostrano l'avviso: No suitable file cache medium found or requirement exceeded limits for all options.

Causa

Le dimensioni della cache dei file calcolate superano sia la RAM del nodo disponibile sia lo spazio di archiviazione SSD locale disponibile.

Risoluzione

  • Utilizza l'opzione di montaggio only-dir per limitare il volume a una sottodirectory più piccola con meno oggetti.
  • Aumenta i limiti delle risorse del sidecar Cloud Storage FUSE.
  • Utilizza un tipo di nodo con più memoria o abilita gli SSD locali nel pool di nodi.

Monitorare lo stato utilizzando gli eventi PersistentVolume

GKE registra gli eventi e gli errori di configurazione chiave nel PV. Per controllare questi eventi, esegui questo comando:

kubectl describe pv PV_NAME

Al termine della scansione del bucket, viene visualizzato un evento ScanOperationSucceeded. Se utilizzi il profilo gcsfusecsi-serving, visualizzi un evento AnywhereCacheSyncSucceeded dopo che il livello di memorizzazione nella cache è operativo.

Monitorare lo stato utilizzando i log del driver CSI

Il driver CSI di Cloud Storage FUSE registra decisioni di configurazione dettagliate e informazioni sul rendimento. Per visualizzare questi log in Cloud Logging, utilizza la seguente query:

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

Visualizzare gli approfondimenti sui suggerimenti

Per comprendere gli indicatori di input specifici e le decisioni prese dalla logica di ottimizzazione automatica, cerca la stringa GCSFuseCSIRecommendation nei log del driver CSI. Il payload JSON risultante fornisce metriche dettagliate, tra cui le seguenti:

  • inputSignals: il conteggio degli oggetti bucket, le dimensioni totali dei dati e le risorse del nodo disponibili (RAM e archiviazione temporanea).
  • decision: le dimensioni della cache calcolate finali e il supporto di archiviazione selezionato (ram o 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
    }
  },
  ...
}

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse create in questa guida, segui questi passaggi:

  1. Elimina il deployment:

    kubectl delete deployment my-deployment -n NAMESPACE

    Sostituisci NAMESPACE con lo spazio dei nomi Kubernetes in cui hai creato il deployment.

  2. Elimina PersistentVolumeClaim:

    kubectl delete pvc my-pvc -n NAMESPACE

    Sostituisci NAMESPACE con lo spazio dei nomi Kubernetes in cui hai creato il PVC.

  3. Elimina PersistentVolume:

    kubectl delete pv my-pv

  4. Se hai utilizzato il profilo gcsfusecsi-serving o hai attivato manualmente Rapid Cache, segui le istruzioni per disattivare una cache per non incorrere più in addebiti per le istanze di cache.

Passaggi successivi