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 specifiche delle risorse per il container sidecar del driver CSI di Cloud Storage FUSE. Configurando queste risorse, come un'immagine privata, un buffer di scrittura personalizzato e un volume di cache di lettura personalizzato, puoi avere 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, tempi di elaborazione più veloci e potenzialmente ridurre il 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 Google Cloud contenuti, consulta Ruoli e attività comuni degli utenti GKE.

Prima di iniziare, familiarizza 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 che siano accessibili come file system locali per le 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 contribuisce 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 container sidecar utilizzando annotazioni come gke-gcsfuse/cpu-limit e gke-gcsfuse/memory-limit. Il modello di container sidecar garantisce inoltre che l'istanza di 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, in particolare nei workload Job o nei pod con un RestartPolicy di Never.

Compatibilità con Cloud Service Mesh e OSS Istio

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 di 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 o Cloud Service Mesh in modo da escludere l'indirizzo IP del server di metadati GKE dal reindirizzamento.

Configurare un buffer di scrittura personalizzato

Cloud Storage FUSE esegue lo staging delle scritture in una directory locale, quindi le carica in 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. Questa opzione è 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 SSD locale, uno spazio di archiviazione basato su Persistent Disk e un disco RAM (memoria). GKE utilizzerà il volume specificato per il buffering di scrittura dei file. Per scoprire di più su queste opzioni, consulta Selezionare lo spazio di archiviazione per il backup della cache dei file.

Per utilizzare un volume buffer personalizzato supportato da un Persistent Disk, devi specificare un fsGroup diverso da zero in 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 il PVC monta i bucket Cloud Storage come volumi permanenti utilizzando il driver CSI di Cloud Storage FUSE.

Il seguente esempio 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 del PVC predefinito.

Configurare un volume di cache di lettura personalizzato

Questa sezione descrive come configurare un volume di cache personalizzato per la memorizzazione nella cache di 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 fsGroup diverso da zero in 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 il PVC monta i bucket Cloud Storage come volumi permanenti utilizzando il driver CSI di Cloud Storage FUSE.

Il seguente esempio mostra come utilizzare un PersistentVolumeClaim predefinito come volume di 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 del PersistentVolumeClaim predefinito.

Configurare un'immagine privata per il container sidecar

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

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

  1. Consulta questa tabella di compatibilità di GKE per trovare un'immagine container sidecar pubblico compatibile.
  2. Esegui il pull nell'ambiente locale e il push nel registro container privato.

  3. Nel manifest, specifica un container denominato gke-gcsfuse-sidecar con il solo 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 registro container 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.

Configurare 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 spazio di archiviazione temporanea

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

  • CPU senza limiti
  • Memoria senza limiti
  • Spazio di archiviazione temporanea senza limiti

Limiti (prima della versione 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

Limiti:

  • 50m CPU
  • 250 MiB di memoria
  • Spazio di archiviazione temporanea senza limiti

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 viene impostata una delle richieste o dei limiti e l'altra non viene impostata, le richieste e i limiti delle risorse dei pod verranno impostati come uguali. Se vengono impostate sia la richiesta che i limiti, i pod utilizzano le richieste e i limiti delle risorse esatti che hai specificato. Se non imposti alcun valore, vengono applicate direttamente le risorse predefinite (descritte sopra).
  • Cluster Autopilot: se viene impostata una delle richieste o dei limiti e l'altra non viene impostata, le richieste e i limiti delle risorse dei pod verranno impostati come uguali. Consulta Impostare i limiti delle risorse in Autopilot per capire in che modo le sostituzioni delle risorse e i valori delle risorse predefiniti impostati influiscono sul comportamento dei pod.

Per sovrascrivere i valori predefiniti per il container gke-gcsfuse-sidecar, puoi specificare facoltativamente 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 GKE 1.32.3-gke.1717000 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 il container gke-gcsfuse-sidecar ha già tutti i limiti (cpu-limit, memory-limit, e ephemeral-storage-limit) non impostati e il container gke-gcsfuse-metadata-prefetch ha già ephemeral-storage-limit non impostato, quindi l'impostazione di questi limiti su "0" in un cluster con GKE versione 1.32.3-gke.1717000 o successive non avrà alcun effetto.

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

(Facoltativo) Analizzare le prestazioni utilizzando Cloud Profiler

Puoi utilizzare Cloud Profiler per ottenere una visibilità continua e granulare sul consumo di risorse delle applicazioni che utilizzano molto spazio di archiviazione. I dati granulari possono aiutarti a monitorare in modo proattivo l'utilizzo di CPU e memoria utilizzata nel driver CSI di Cloud Storage FUSE e nel relativo container sidecar. Le informazioni che ottieni dai dati di Cloud Profiler possono aiutarti a identificare i percorsi di codice inefficienti, ottimizzare l'allocazione delle risorse e risolvere problemi complessi come perdite di memoria o eventi out of memory (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 abilitare manualmente.

Prima di abilitare 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 creare il profilo.

Abilitare l'API

Abilita l'API Cloud Profiler

Concedere 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 per impostazione predefinita sulla rete host, 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 nodo:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • 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.

Concedere 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 workload.

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: l'ID del tuo Google Cloud progetto.
  • PROJECT_NUMBER: il numero del Google Cloud progetto.
  • NAMESPACE: il nome dello spazio dei nomi Kubernetes.
  • KSA_NAME: il nome del service account Kubernetes.

Abilitare Cloud Profiler per i workload sidecar

Per generare i profili per il montatore sidecar e il processo gcsfuse sottostante, imposta l'attributo del volume enableCloudProfilerForSidecar su "true" nella specifica del workload. L'abilitazione di Cloud Profiler per il container sidecar lo abilita 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 consolle. Utilizza il filtro Nome servizio come segue per analizzare il componente che stai esaminando:

Componente Filtro per nome servizio
Driver del nodo gcs-fuse-csi-driver
Montatore sidecar 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) Disabilitare la profilazione GCSFuse

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

Per disabilitare la profilazione gcsfuse mantenendo abilitata 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"

Configurare la verbosità dei log

Per impostazione predefinita, il container gke-gcsfuse-sidecar genera log a livello info ed error. Tuttavia, per il debug o un'analisi più dettagliata, potresti dover modificare la verbosità dei log. Questa sezione descrive come aumentare o diminuire il livello di logging.

Puoi utilizzare le opzioni di montaggio per configurare la verbosità dei log oppure 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à dei log è applicata:

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

Risoluzione dei problemi

Per ulteriori informazioni 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