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

Questa guida mostra come configurare le risorse per il container sidecar del driver CSI Cloud Storage FUSE, inclusa la configurazione di un'immagine privata, di un buffer di scrittura personalizzato e di un volume della cache di lettura personalizzato. In genere, non è necessario modificare queste impostazioni.

Il driver CSI di Cloud Storage FUSE utilizza un container sidecar personalizzabile per montare e accedere in modo efficiente ai bucket Cloud Storage. Configurando il sidecar, puoi ottimizzare le prestazioni dell'applicazione e l'utilizzo delle risorse, il che può portare a un accesso più rapido ai dati, tempi di elaborazione più veloci e potenzialmente a un consumo complessivo di risorse inferiore per la tua applicazione.

Questa guida è rivolta a sviluppatori, amministratori e architetti che vogliono ottimizzare le prestazioni, la sicurezza e l'efficienza delle loro applicazioni che interagiscono con GKE.

Prima di leggere questa pagina, assicurati di conoscere le basi di Cloud Storage, Kubernetes e i concetti di containerizzazione.

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 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 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 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 Job o nei pod con un RestartPolicy di Never.

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

Configura buffer di scrittura personalizzato

Cloud Storage FUSE esegue la gestione temporanea 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 preparare i file nelle operazioni di scrittura. Ciò è 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 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 della scrittura dei file. Per scoprire di più su queste opzioni, vedi 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 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 è necessaria se il tuo PVC monta i bucket Cloud Storage come volumi permanenti utilizzando il driver CSI di Cloud Storage FUSE.

Il seguente esempio mostra come utilizzare un oggetto 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 della 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 archiviazione supportato da GKE, ad esempio un PersistentVolumeClaim, e GKE utilizzerà il volume specificato per la memorizzazione nella cache dei file. È utile se devi memorizzare nella cache file più grandi di 10 GiB sui cluster Autopilot.

Per utilizzare un volume della cache 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 è necessaria se il tuo 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 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 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 privata:

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

  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 registro dei 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.

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 spazio 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 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:

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

Limitazioni:

  • 50m CPU
  • 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 uno dei valori di richiesta o limite è impostato e l'altro non è impostato, i limiti e le richieste di risorse dei pod verranno impostati come uguali. Se vengono impostati sia la richiesta che i limiti, i pod utilizzano esattamente le richieste e i limiti delle risorse che specifichi. Se non imposti alcun valore, le risorse predefinite (descritte sopra) vengono applicate direttamente.
  • 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 la sezione 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 contenitore 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 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) annullati e il container gke-gcsfuse-metadata-prefetch ha già ephemeral-storage-limit annullato, quindi impostare questi limiti su "0" su 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. Ciò è utile quando non riesci a decidere la quantità di risorse necessarie per la funzionalità di precaricamento dei metadati per i tuoi carichi di lavoro e vuoi consentire al precaricamento dei metadati di utilizzare tutte le risorse disponibili su un nodo.

(Facoltativo) Analizza le prestazioni utilizzando Cloud Profiler

Puoi utilizzare Cloud Profiler per ottenere una visibilità continua e granulare sul consumo di risorse delle tue 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 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 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 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.

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, l'autenticazione avviene utilizzando il account di servizio IAM associato al nodo GKE, anziché 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.

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 carico di lavoro.

Concedi il ruolo roles/cloudprofiler.agent al KSA utilizzato dal tuo 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 contenitore 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 nel seguente modo per analizzare il componente che stai esaminando:

Componente Filtro per nome del servizio
Node Driver 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) Disattiva la profilazione di GCSFuse

Per impostazione predefinita, l'abilitazione della profilazione per il container sidecar profila anche il processo gcsfuse sottostante. Potresti voler disattivare la profilazione gcsfuse per ridurre l'overhead delle risorse o concentrare l'analisi esclusivamente sul rendimento del container collaterale.

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"

Configurare il livello di dettaglio del logging

Per impostazione predefinita, il container gke-gcsfuse-sidecar genera log a livello info e error. Tuttavia, per il debug o un'analisi più dettagliata, potresti dover modificare 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

Una volta eseguito 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