Configura il container sidecar del driver CSI di Cloud Storage FUSE per GKE

Questo documento mostra come configurare le impostazioni delle risorse per il container sidecar del driver CSI di Cloud Storage FUSE in Google Kubernetes Engine (GKE).

Per ottimizzare le prestazioni e l'utilizzo delle risorse della tua applicazione in GKE, configura impostazioni delle risorse specifiche per il container sidecar del driver CSI di Cloud Storage FUSE. Configurando queste risorse, ad esempio un'immagine privata, un buffer di scrittura personalizzato e un volume della cache di lettura personalizzato, puoi ottenere un maggiore controllo sul modo in cui le tue applicazioni interagiscono con Cloud Storage. Queste configurazioni possono portare a un accesso più rapido ai dati, a tempi di elaborazione più veloci e potenzialmente a una riduzione del consumo complessivo di risorse nei cluster GKE.

Questo documento è rivolto a sviluppatori, amministratori e architetti che ottimizzano le prestazioni delle applicazioni. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Google Cloud , consulta Ruoli e attività comuni degli utenti GKE.

Prima di iniziare, acquisisci familiarità con i seguenti concetti relativi a workload e spazio di archiviazione:

Come funziona il container sidecar

Il driver CSI di Cloud Storage FUSE utilizza un container sidecar per montare i bucket Cloud Storage in modo da renderli accessibili come file system locali alle applicazioni Kubernetes. Questo container sidecar, denominato gke-gcsfuse-sidecar, viene eseguito insieme al container del workload all'interno dello stesso pod. Quando il driver rileva l'annotazione gke-gcsfuse/volumes: "true" in una specifica del pod, inserisce automaticamente il container sidecar. Questo approccio con container sidecar aiuta a garantire la sicurezza e a gestire le risorse in modo efficace.

Il container sidecar gestisce le complessità del montaggio dei bucket Cloud Storage e fornisce l'accesso al file system alle applicazioni senza richiedere la gestione diretta del runtime di Cloud Storage FUSE. Puoi configurare i limiti delle risorse per il contenitore sidecar utilizzando annotazioni come gke-gcsfuse/cpu-limit e gke-gcsfuse/memory-limit. Il modello di container sidecar garantisce inoltre che l'istanza Cloud Storage FUSE sia legata al ciclo di vita del workload, impedendole di consumare risorse inutilmente. Ciò significa che il container sidecar termina automaticamente quando i container del workload escono, soprattutto nei workload dei job o nei pod con un RestartPolicy di Never.

Compatibilità con Istio OSS

Il container sidecar del driver CSI di Cloud Storage FUSE e Istio possono coesistere ed essere eseguiti contemporaneamente nel pod. Tuttavia, in GKE versione 1.29 e successive, potresti riscontrare errori di autenticazione se Cloud Storage FUSE tenta di connettersi al server dei metadati prima che il proxy Istio sia pronto. Se riscontri questi errori di autenticazione, puoi risolvere il problema aggiungendo traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32 a metadata.annotations nella specifica del pod. Questa annotazione configura Istio in modo da escludere il reindirizzamento dell'indirizzo IP del server di metadati GKE.

Configura buffer di scrittura personalizzato

Cloud Storage FUSE gestisce le scritture in una directory locale, quindi le carica su Cloud Storage durante le operazioni close o fsync.

Questa sezione descrive come configurare un volume buffer personalizzato per il buffering di scrittura di Cloud Storage FUSE. Questo scenario potrebbe essere applicabile se devi sostituire il volume emptyDir predefinito per Cloud Storage FUSE per eseguire lo staging dei file nelle operazioni di scrittura. Questo è utile se devi scrivere file di dimensioni superiori a 10 GiB sui cluster Autopilot.

Puoi specificare qualsiasi tipo di spazio di archiviazione supportato dal driver CSI di Cloud Storage FUSE per la memorizzazione nella cache dei file, ad esempio un'unità SSD locale, uno spazio di archiviazione basato su Persistent Disk e un disco RAM (memoria). GKE utilizzerà il volume specificato per il buffering della scrittura dei file. Per scoprire di più su queste opzioni, consulta Seleziona lo spazio di archiviazione per il backup della cache file.

Per utilizzare un volume buffer personalizzato supportato da un Persistent Disk, devi specificare un valore fsGroup diverso da zero in securityContext del pod. Questo passaggio concede le autorizzazioni di lettura o scrittura necessarie per il volume al contenitore sidecar non root. Questa impostazione non è obbligatoria se la PVC monta i bucket Cloud Storage come volumi permanenti utilizzando il driver CSI di Cloud Storage FUSE.

L'esempio seguente mostra come utilizzare un PersistentVolumeClaim predefinito come volume buffer:

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

Sostituisci quanto segue:

  • FS_GROUP: l'ID fsGroup.
  • BUFFER_VOLUME_PVC: il nome PVC predefinito.

Configura il volume della cache di lettura personalizzata

Questa sezione descrive come configurare un volume di cache personalizzato per la memorizzazione nella cache in lettura di Cloud Storage FUSE.

Questo scenario potrebbe essere applicabile se devi sostituire il volume emptyDir predefinito per Cloud Storage FUSE per memorizzare nella cache i file nelle operazioni di lettura. Puoi specificare qualsiasi tipo di spazio di archiviazione supportato da GKE, ad esempio un PersistentVolumeClaim, e GKE utilizzerà il volume specificato per la memorizzazione nella cache dei file. Questa opzione è utile se devi memorizzare nella cache file di dimensioni superiori a 10 GiB sui cluster Autopilot.

Per utilizzare un volume di cache personalizzato supportato da un Persistent Disk, devi specificare un valore fsGroup diverso da zero nel securityContext del pod. Questo passaggio concede le autorizzazioni di lettura o scrittura necessarie per il volume al container sidecar non root. Questa impostazione non è obbligatoria se la PVC monta i bucket Cloud Storage come volumi permanenti utilizzando il driver CSI di Cloud Storage FUSE.

L'esempio seguente mostra come utilizzare un oggetto PersistentVolumeClaim predefinito come volume della cache:

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

Sostituisci quanto segue:

  • FS_GROUP: l'ID fsGroup.
  • CACHE_VOLUME_PVC: il nome PersistentVolumeClaim predefinito.

Configura un'immagine privata per il container sidecar

Questa sezione descrive come utilizzare l'immagine container sidecar se la ospiti in un Container Registry privato. Questo scenario potrebbe essere applicabile se devi utilizzare nodi privati per motivi di sicurezza.

Per configurare e utilizzare l'immagine container sidecar privata, segui questi passaggi:

  1. Consulta questa tabella di compatibilità di GKE per trovare un'immagine container sidecar pubblica compatibile.
  2. Estrailo nel tuo ambiente locale e invialo al tuo registro dei container privati.

  3. Nel manifest, specifica un container denominato gke-gcsfuse-sidecar con solo il campo dell'immagine. GKE utilizzerà l'immagine container sidecar specificata per prepararsi all'inserimento del container sidecar.

    Ecco un esempio:

    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.

    Sostituisci quanto segue:

    • PRIVATE_REGISTRY: il tuo Container Registry privato. Ad esempio, us-central1-docker.pkg.dev/my-project/my-registry.
    • PRIVATE_IMAGE_TAG: il tag dell'immagine del container sidecar privato. Ad esempio, v1.17.1-gke.1.

Configura le risorse del container sidecar

Per impostazione predefinita, il container gke-gcsfuse-sidecar è configurato con le seguenti richieste e limiti di risorse per i cluster Standard e Autopilot:

Richieste:

  • 250m CPU
  • 256 MiB di memoria
  • 5 GiB di archiviazione temporanea

Limiti (GKE versione 1.29.1-gke.1670000 e successive):

  • CPU illimitata
  • memoria illimitata
  • spazio di archiviazione temporanea illimitato

Limiti (prima della versione di GKE 1.29.1-gke.1670000):

  • 250m CPU
  • 256 MiB di memoria
  • 5 GiB di spazio di archiviazione temporanea

Per impostazione predefinita, il container gke-gcsfuse-metadata-prefetch è configurato con le seguenti richieste e limiti di risorse per i cluster Standard e Autopilot:

Richieste:

  • 10m CPU
  • 10 MiB di memoria
  • 10 MiB di spazio di archiviazione temporanea

Limitazioni:

  • CPU 50 m
  • 250 MiB di memoria
  • spazio di archiviazione temporanea illimitato

Nei cluster Standard e Autopilot, puoi sovrascrivere i valori predefiniti. Il modo in cui GKE gestisce le risorse dei container dipende dalla modalità di funzionamento del cluster:

  • Cluster standard: se una delle richieste o dei limiti è impostata e l'altra non è impostata, i limiti e le richieste di risorse dei pod verranno impostati come uguali. Se sono impostati sia le richieste che i limiti, i pod utilizzano le richieste e i limiti delle risorse esatti che specifichi. Se non imposti alcun valore, vengono applicate direttamente le risorse predefinite (descritte sopra).
  • Cluster Autopilot: se una delle richieste o dei limiti è impostata e l'altra non è impostata, i limiti e le richieste di risorse dei pod verranno impostati come uguali. Consulta Impostazione dei limiti delle risorse in Autopilot per capire in che modo gli override delle risorse e i valori predefiniti delle risorse impostati influiscono sul comportamento dei pod.

Per sovrascrivere i valori predefiniti per il container gke-gcsfuse-sidecar, puoi facoltativamente specificare l'annotazione gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] come mostrato nell'esempio seguente:

Per sovrascrivere i valori predefiniti per il container gke-gcsfuse-metadata-prefetch (a partire dalla versione 1.32.3-gke.1717000 di GKE e successive), puoi specificare facoltativamente l'annotazione 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] come mostrato nell'esempio seguente:

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

Puoi utilizzare il valore "0" per annullare l'impostazione di eventuali limiti o richieste di risorse, ma tieni presente che per il container gke-gcsfuse-sidecar l'impostazione di tutti i limiti (cpu-limit, memory-limit e ephemeral-storage-limit) è già annullata e per il container gke-gcsfuse-metadata-prefetch l'impostazione di ephemeral-storage-limit è già annullata, quindi l'impostazione di questi limiti su "0" in un cluster con GKE versione 1.32.3-gke.1717000 o successive non avrebbe alcun effetto.

Ad esempio, l'impostazione gke-gcsfuse/metadata-prefetch-memory-limit: "0" indica che vuoi annullare l'impostazione del limite di memoria del container gke-gcsfuse-metadata-prefetch. Questo è utile quando non riesci a decidere la quantità di risorse necessarie per i tuoi workload per la funzionalità di precaricamento dei metadati e vuoi consentire al precaricamento dei metadati di consumare tutte le risorse disponibili su un nodo.

(Facoltativo) Analizza le prestazioni utilizzando Cloud Profiler

Puoi utilizzare Cloud Profiler per ottenere una visibilità granulare e continua sul consumo di risorse delle tue applicazioni con un utilizzo intensivo dello spazio di archiviazione. I dati granulari possono aiutarti a monitorare in modo proattivo l'utilizzo della CPU e la memoria utilizzata nel driver CSI di Cloud Storage FUSE e nel relativo container sidecar. Gli approfondimenti che ottieni dai dati di Cloud Profiler possono aiutarti a identificare percorsi di codice inefficienti, ottimizzare l'allocazione delle risorse e risolvere problemi complessi come perdite di memoria o eventi di memoria insufficiente (OOM) imprevisti prima che influiscano sulla stabilità del servizio.

L'utilizzo di Cloud Profiler è facoltativo ed è progettato per gli amministratori che richiedono una diagnostica dettagliata delle prestazioni. Cloud Profiler è abilitato per impostazione predefinita per il driver del nodo. Per i container sidecar, è una funzionalità attivabile che puoi attivare manualmente.

Prima di attivare Cloud Profiler

Per utilizzare Cloud Profiler con il driver CSI di Cloud Storage FUSE, assicurati di utilizzare GKE versione 1.36.0-gke.2403000 o successive. Prima di generare i profili, devi abilitare l'API Cloud Profiler e configurare le autorizzazioni IAM appropriate per i componenti di cui vuoi eseguire la profilazione.

Abilita l'API

Abilita l'API Cloud Profiler

Concedi le autorizzazioni al driver del nodo

Per inviare i dati di profilazione a Cloud Profiler, il driver del nodo richiede le autorizzazioni IAM. Poiché il driver del nodo viene eseguito sulla rete host per impostazione predefinita, esegue l'autenticazione utilizzando il account di servizio IAM associato al nodo GKE, anziché utilizzare Workload Identity Federation for GKE.

Concedi il ruolo roles/cloudprofiler.agent al account di servizio del tuo nodo:

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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • NODE_SERVICE_ACCOUNT: il account di servizio IAM utilizzato dai nodi GKE. In genere si tratta del account di servizio Compute Engine predefinito, ad esempio PROJECT_NUMBER-compute@, a meno che i nodi non siano configurati per utilizzare un service account diverso.

Concedi le autorizzazioni al container sidecar

Per inviare i dati di profilazione a Cloud Profiler, il container sidecar e il processo gcsfuse richiedono le autorizzazioni IAM. Questi componenti eseguono l'autenticazione utilizzando Workload Identity Federation for GKE, che utilizza il service account Kubernetes (KSA) associato al pod del carico di lavoro.

Concedi il ruolo roles/cloudprofiler.agent al KSA utilizzato dal pod:

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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • PROJECT_NUMBER: il numero del progetto Google Cloud .
  • NAMESPACE: il nome dello spazio dei nomi Kubernetes.
  • KSA_NAME: il nome del tuo service account Kubernetes.

Abilita Cloud Profiler per i workload sidecar

Per generare profili per il montatore sidecar e il processo gcsfuse sottostante, imposta l'attributo del volume enableCloudProfilerForSidecar su "true" nella specifica del workload. L'attivazione di Cloud Profiler per il container sidecar lo attiva automaticamente anche per il processo gcsfuse sottostante.

Sostituisci BUCKET_NAME con il nome del tuo bucket Cloud Storage:

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

Visualizzare i dati di profilazione

Per visualizzare i dati di profilazione, vai alla pagina Cloud Profiler nella Google Cloud console. Utilizza il filtro Nome servizio come segue per analizzare il componente che stai esaminando:

Componente Filtro per nome del servizio
Node Driver gcs-fuse-csi-driver
Sidecar Mounter gke-gcsfuse-sidecar
GCSFuse gcsfuse

Cloud Profiler identifica ogni istanza utilizzando il formato POD_NAME_POD_UID. In questo modo, ogni istanza viene identificata in modo univoco anche se un pod viene riavviato.

(Facoltativo) Disattiva la profilazione di GCSFuse

Per impostazione predefinita, l'attivazione della profilazione per il container sidecar profila anche il processo gcsfuse sottostante. Potresti voler disattivare la profilazione gcsfuse per ridurre il sovraccarico di risorse o concentrare l'analisi esclusivamente sulle prestazioni del container sidecar.

Per disattivare la profilazione gcsfuse mantenendo attiva la profilazione sidecar, aggiungi enable-cloud-profiler=false all'attributo mountOptions nella specifica del volume.

Sostituisci BUCKET_NAME con il nome del tuo bucket Cloud Storage:

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

Configura il livello di dettaglio del logging

Per impostazione predefinita, il container gke-gcsfuse-sidecar genera log a livello di info e error. Tuttavia, per il debug o un'analisi più dettagliata, potrebbe essere necessario regolare il livello di dettaglio della registrazione. Questa sezione descrive come aumentare o diminuire il livello di logging.

Puoi utilizzare le opzioni di montaggio per configurare il livello di dettaglio della registrazione o utilizzare la funzionalità del driver CSI per convertire i valori degli attributi del volume nelle impostazioni di configurazione gcsfuse necessarie.

Nel manifest del pod di destinazione, includi le seguenti configurazioni:

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

Per utilizzare le opzioni di montaggio, includi la seguente configurazione nel manifest del pod di destinazione:

  mountOptions: "logging:severity:LOGGING_SEVERITY"

Sostituisci quanto segue:

  • BUCKET_NAME: il nome del bucket Cloud Storage.
  • LOGGING_SEVERITY: uno dei seguenti valori, in base ai tuoi requisiti:
    • trace
    • debug
    • info
    • warning
    • error

Dopo il deployment del pod, il driver CSI avvia gcsfuse con il livello di logging appena configurato.

Puoi utilizzare il seguente filtro per verificare se la gravità del logging è applicata:

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

Risoluzione dei problemi

Per saperne di più sulla risoluzione dei problemi del driver CSI di Cloud Storage FUSE, consulta la guida alla risoluzione dei problemi nella documentazione del progetto GitHub.

Passaggi successivi