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 di 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 FUSE di Cloud Storage sia legata al ciclo di vita del workload, impedendole di consumare risorse inutilmente. Ciò significa che il container sidecar termina automaticamente quando escono i container del workload, 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 suPersistent Diski e un disco RAM (memoria). GKE utilizzerà il volume specificato per il buffering di 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 il volume buffer personalizzato, devi specificare un valore fsGroup diverso da zero.

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 il volume della cache personalizzata, devi specificare un valore fsGroup diverso da zero.

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 inseriscilo 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 container sidecar privata. 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 minuti
  • 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 lo è, 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 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.

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à della registrazione è 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