Accedere ai bucket Cloud Storage con il driver CSI di Cloud Storage FUSE

Filesystem in Userspace (FUSE) è un'interfaccia utilizzata per esportare un file system nel kernel di Linux. Cloud Storage FUSE ti consente di montare i bucket Cloud Storage come file system in modo che le applicazioni possano accedere agli oggetti in un bucket utilizzando operazioni di I/O file comuni (ad es. apri, leggi, scrivi, chiudi) anziché API specifiche del cloud.

Il driver CSI di Cloud Storage FUSE ti consente di sfruttare l'API Kubernetes per utilizzare i bucket Cloud Storage preesistenti come volumi. Le tue applicazioni possono caricare e scaricare oggetti utilizzando la semantica del file system Cloud Storage FUSE. Il driver CSI di Cloud Storage FUSE offre un'esperienza completamente gestita basata sul driver CSI di Google Cloud Storage FUSE open source.

Il driver supporta in modo nativo i seguenti modi per configurare i volumi basati su Cloud Storage:

Puoi utilizzare il driver CSI di Cloud Storage FUSE con la cache dei file per migliorare le prestazioni di lettura delle applicazioni che gestiscono file di piccole dimensioni dai bucket Cloud Storage. La funzionalità della cache dei file di Cloud Storage FUSE è una cache di lettura basata su client che consente di eseguire più rapidamente letture ripetute dei file dallo spazio di archiviazione della cache che preferisci. Puoi scegliere tra una serie di opzioni di archiviazione per la cache di lettura, tra cui SSD locali e archiviazione basata su Persistent Disk, in base alle tue esigenze di prezzo e prestazioni. Devi attivare la cache dei file con il driver CSI di Cloud Storage FUSE. Per scoprire di più sulle best practice per la memorizzazione nella cache, consulta Rendimento di Cloud Storage FUSE.

Vantaggi

  • Il driver CSI di Cloud Storage FUSE sul tuo cluster attiva il deployment automatico e la gestione del driver. Il driver funziona sia nei cluster Standard sia nei cluster Autopilot.
  • Il driver CSI di Cloud Storage FUSE non richiede l'accesso privilegiato tipicamente richiesto dai client FUSE. In questo modo, puoi adottare una strategia di sicurezza migliore.
  • Il supporto dei volumi effimeri CSI semplifica la configurazione e la gestione dei volumi eliminando la necessità di oggetti PersistentVolumeClaim e PersistentVolume.
  • Il driver CSI di Cloud Storage FUSE supporta le modalità di accesso ReadWriteMany, ReadOnlyMany e ReadWriteOnce.
  • Puoi utilizzare la federazione delle identità per i carichi di lavoro per GKE per gestire l'autenticazione e avere un controllo granulare su come i tuoi pod accedono agli oggetti Cloud Storage. L'accesso uniforme a livello di bucket è necessario per i carichi di lavoro di lettura/scrittura quando utilizzi la federazione delle identità per i carichi di lavoro.
  • Se esegui l'addestramento ML e il servizio di carichi di lavoro con framework come Ray, PyTorch, Spark e TensorFlow, la portabilità e la semplicità fornite dal driver CSI Cloud Storage FUSE ti consentono di eseguire i carichi di lavoro direttamente sui tuoi cluster GKE senza ulteriori modifiche al codice.
  • Puoi leggere gli oggetti Cloud Storage con la cache dei file abilitata per migliorare le prestazioni di lettura. La memorizzazione nella cache dei file accelera le letture ripetute, poiché consente di caricare gli oggetti dallo spazio di archiviazione locale. Per scoprire di più sui vantaggi della memorizzazione nella cache dei file, consulta la documentazione di Cloud Storage FUSE.
  • Con Cloud Storage FUSE versione 2.4.0 e la cache dei file abilitata, puoi utilizzare la funzionalità di download parallelo per accelerare la lettura di file di grandi dimensioni da Cloud Storage per download multithread. Puoi utilizzare questa funzionalità per migliorare i tempi di caricamento dei modelli, in particolare per le letture di dimensioni superiori a 1 GB (ad esempio, fino al doppio della velocità durante il caricamento di Llama2 70B).
  • Puoi utilizzare i volumi Cloud Storage FUSE nei container di inizializzazione.
  • Puoi visualizzare approfondimenti sulle metriche per Cloud Storage FUSE, tra cui l'utilizzo del file system, di Cloud Storage e della cache dei file.

Prima di iniziare

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

  • Attiva l'API Google Kubernetes Engine.
    • Attiva l'API Google Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installa e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, ottieni la versione più recente eseguendo gcloud components update.
  • Crea i tuoi bucket Cloud Storage. Per migliorare le prestazioni, imposta il campo Location type su Region e seleziona una regione in cui è in esecuzione il tuo cluster GKE.

Limitazioni

Requisiti

Per utilizzare il driver CSI di Cloud Storage FUSE, i cluster devono soddisfare i seguenti requisiti:

Abilita il driver CSI di Cloud Storage FUSE

Per creare un cluster standard con il driver CSI di Cloud Storage FUSE attivo, puoi utilizzare gcloud CLI:

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del tuo cluster.
  • VERSION: il numero di versione di GKE. Devi selezionare 1.24 o versioni successive.
  • LOCATION: la posizione di Compute Engine per il cluster.
  • PROJECT_ID: il tuo ID progetto.

Per attivare il driver in un cluster standard esistente, utilizza il comando gcloud container clusters update:

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

Sostituisci quanto segue:

Dopo aver attivato il driver CSI di Cloud Storage FUSE, puoi utilizzarlo nei volumi Kubernetes specificando il nome del driver e del provisioning: gcsfuse.csi.storage.gke.io.

Configurare l'accesso ai bucket Cloud Storage utilizzando la federazione delle identità per i carichi di lavoro di GKE

Per rendere accessibili i bucket Cloud Storage dal tuo cluster GKE utilizzando la federazione delle identità per i carichi di lavoro per GKE, segui questi passaggi. Per ulteriori informazioni, consulta Configurare le applicazioni per utilizzare la federazione delle identità per i carichi di lavoro per GKE.

  1. Recupera le credenziali per il tuo cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster in cui è abilitata la federazione delle identità per i carichi di lavoro per GKE.
    • LOCATION: la posizione di Compute Engine per il cluster.

  2. Crea uno spazio dei nomi da utilizzare per l'account di servizio Kubernetes. Puoi anche utilizzare lo spazio dei nomi default o qualsiasi spazio dei nomi esistente.

    kubectl create namespace NAMESPACE

    Sostituisci quanto segue:

    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per il service account Kubernetes.

  3. Crea un account di servizio Kubernetes da utilizzare per la tua applicazione. Puoi anche utilizzare qualsiasi account di servizio Kubernetes esistente in qualsiasi spazio dei nomi, incluso l'account di servizio Kubernetes default.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Sostituisci quanto segue:

    • KSA_NAME: il nome del nuovo service account Kubernetes.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per il service account Kubernetes.

  4. Concedi uno dei ruoli IAM per Cloud Storage al service account Kubernetes.

    Puoi concedere il ruolo al tuo service account Kubernetes per accedere solo a un bucket Cloud Storage specifico utilizzando il seguente comando:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Sostituisci quanto segue:

    • BUCKET_NAME: il nome del bucket Cloud Storage.
    • PROJECT_NUMBER: il numero numerico del progetto del tuo cluster GKE. Per trovare il numero del progetto, consulta Identificazione dei progetti.
    • PROJECT_ID: l'ID del progetto del tuo cluster GKE.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per il service account Kubernetes.
    • KSA_NAME: il nome del nuovo service account Kubernetes.
    • ROLE_NAME: il ruolo IAM da assegnare al tuo account di servizio Kubernetes.
      • Per i carichi di lavoro di sola lettura, utilizza il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer).
      • Per i carichi di lavoro di lettura/scrittura, utilizza il ruolo Utente oggetto archiviazione (roles/storage.objectUser).

    Facoltativamente, puoi concedere il ruolo al tuo account di servizio Kubernetes per accedere a tutti i bucket Cloud Storage del progetto utilizzando il seguente comando:

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Sostituisci quanto segue:

    • GCS_PROJECT: l'ID progetto dei tuoi bucket Cloud Storage.
    • PROJECT_NUMBER: il numero numerico del progetto del tuo cluster GKE. Per trovare il numero del progetto, consulta Identificazione dei progetti.
    • PROJECT_ID: l'ID del progetto del tuo cluster GKE.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per il service account Kubernetes.
    • KSA_NAME: il nome del nuovo service account Kubernetes.
    • ROLE_NAME: il ruolo IAM da assegnare al tuo account di servizio Kubernetes.
      • Per i carichi di lavoro di sola lettura, utilizza il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer).
      • Per i carichi di lavoro di lettura/scrittura, utilizza il ruolo Utente oggetto archiviazione (roles/storage.objectUser).

Prepararsi a montare i bucket Cloud Storage FUSE

Questa sezione spiega come prepararsi a montare i bucket FUSE Cloud Storage sui cluster.

Specifica le annotazioni del pod

Il driver CSI si basa sulle annotazioni del pod per identificare se il pod utilizza volumi basati su Cloud Storage. Se il driver rileva le annotazioni necessarie, inietta un contenitore sidecar chiamato gke-gcsfuse-sidecar nel pod del carico di lavoro. Le istanze Cloud Storage FUSE vengono eseguite all'interno del contenitore sidecar e montano i bucket Cloud Storage per il tuo carico di lavoro.

Per consentire al driver CSI di montare i bucket Cloud Storage, assicurati di specificare l'annotazione gke-gcsfuse/volumes: "true" nella specifica del pod, nel campo metadata. Se vuoi che i volumi basati su Cloud Storage vengano utilizzati da altri tipi di carichi di lavoro Kubernetes (ad esempio Job, Deployment o StatefulSet), assicurati di configurare le annotazioni nel campo spec.template.metadata.annotations.

Se utilizzi Istio o Cloud Service Mesh, aggiungi le seguenti annotazioni a livello di pod:

proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'
traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32

Configura le risorse per il contenitore sidecar

Per impostazione predefinita, il contenitore sidecar è configurato con le seguenti richieste di risorse, con i limiti di risorse non impostati (per il cluster standard):

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

Per sovrascrivere questi valori, puoi specificare facoltativamente l'annotazionegke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] come mostrato nell'esempio seguente:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    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

Tieni presenti le seguenti considerazioni quando decidi la quantità di risorse da allocare:

  • Se imposti una sola delle annotazioni per le richieste o i limiti delle risorse, GKE Autopilot applica gli stessi valori per la richiesta e il limite di risorse.
  • Se il pod del tuo carico di lavoro utilizza più volumi Cloud Storage, le risorse dei container sidecar sono condivise da più istanze FUSE di Cloud Storage. Se questo è il tuo caso, valuta la possibilità di aumentare l'allocazione delle risorse per più volumi Cloud Storage.
  • Se i tuoi carichi di lavoro richiedono una maggiore throughput, alloca più CPU al contenitore sidecar. Una CPU insufficiente causerà il throttling di Cloud Storage FUSE.
  • Se i tuoi carichi di lavoro devono elaborare un numero elevato di file e la cache dei metadati FUSE di Cloud Storage è abilitata, aumenta l'allocazione della memoria del contenitore sidecar. Il consumo di memoria di Cloud Storage FUSE per la memorizzazione nella cache dei metadati è proporzionale al numero di file, ma non alle dimensioni dei file. Una memoria insufficiente causerà errori di esaurimento della memoria di Cloud Storage FUSE e l'arresto anomalo dell'applicazione del workload.
  • Per la memorizzazione nella cache dei file, Cloud Storage FUSE memorizza nella cache i file per impostazione predefinita in una directory temporanea locale. Stima lo spazio libero di cui ha bisogno il tuo carico di lavoro per la memorizzazione nella cache dei file e aumenta di conseguenza il limite di spazio di archiviazione temporaneo. Per saperne di più, consulta gli attributi del volume.
  • Per le operazioni di scrittura, per impostazione predefinita Cloud Storage FUSE esegue il commit dei file in una directory temporanea locale prima che vengano caricati nel bucket Cloud Storage. Stima quanto spazio libero è necessario per il tuo carico di lavoro per l'organizzazione in fase di staging quando scrivi file di grandi dimensioni e aumenta di conseguenza il limite di spazio di archiviazione gestione temporanea. Per saperne di più, consulta la sezione Semantica di letture/scritture nella documentazione di GitHub di Cloud Storage FUSE.
  • Puoi utilizzare il valore "0" per annullare l'impostazione di eventuali richieste o limiti di risorse sui cluster standard. Ad esempio, l'annotazione gke-gcsfuse/memory-limit: "0" lascia vuoto il limite di memoria del contenitore sidecar con la richiesta di memoria predefinita. Questa opzione è utile quando non puoi decidere la quantità di risorse di cui ha bisogno Cloud Storage FUSE per i tuoi carichi di lavoro e vuoi che Cloud Storage FUSE consumi tutte le risorse disponibili su un nodo. Dopo aver calcolato i requisiti delle risorse per Cloud Storage FUSE in base alle metriche del carico di lavoro, puoi impostare i limiti appropriati.

Configura un'immagine privata per il contenitore sidecar

Questa sezione descrive come utilizzare l'immagine del contenitore sidecar se la ospiti in un registry dei contenitori privato. Questo scenario potrebbe essere applicabile se devi utilizzare i nodi privati per motivi di sicurezza. Per configurare e utilizzare l'immagine del container sidecar privato:

  1. Consulta questa pagina per cercare un'immagine del contenitore sidecar pubblico compatibile.

  2. Importalo nel tuo ambiente locale e invialo al tuo Container Registry privato.

  3. Nel file manifest, specifica un contenitore denominato gke-gcsfuse-sidecar con solo il campo image. GKE utilizzerà l'immagine del container sidecar specificata per prepararsi all'iniezione 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 registry dei container privato.
  • PRIVATE_IMAGE_TAG: il tag immagine del contenitore sidecar privato.

Configura un volume del buffer di scrittura personalizzato per il contenitore sidecar

Questa sezione descrive come configurare un volume del buffer personalizzato per il buffering delle scritture di Cloud Storage FUSE. Questo scenario potrebbe essere applicabile se devi sostituire il volume emptyDir predefinito per Cloud Storage FUSE per eseguire il commit dei file nelle operazioni di scrittura. Puoi specificare qualsiasi tipo di archiviazione supportato da GKE, ad esempio un PersistentVolumeClaim, e GKE utilizzerà il volume specificato per il buffering della scrittura dei file. Questo è utile se devi scrivere file di dimensioni superiori a 10 GB sui cluster Autopilot. Per utilizzare il volume del buffer personalizzato, devi specificare un valore fsGroup diverso da zero. L'esempio seguente mostra come utilizzare un PVC predefinito come volume del 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 gruppo fs.
  • BUFFER_VOLUME_PVC: il nome del PVC predefinito.

Configura un volume della cache di lettura personalizzata per il contenitore sidecar

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 spazio di archiviazione supportato da GKE, ad esempio un PersistentVolumeClaim, e GKE utilizzerà il volume specificato per la memorizzazione nella cache dei file. Questo è utile se devi memorizzare nella cache file di dimensioni superiori a 10 GB 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 PVC 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 gruppo fs.
  • CACHE_VOLUME_PVC: il nome del PVC predefinito.

Esegui il provisioning del volume come volume temporaneo CSI

I volumi temporanei CSI basati su bucket Cloud Storage sono legati al ciclo di vita del pod. Con questo approccio di provisioning, non devi gestire gli oggetti PersistentVolume e PersistentVolumeClaim associati ai bucket Cloud Storage dopo l'interruzione del pod.

Utilizzare il volume dello spazio di archiviazione temporaneo CSI in un pod

  1. Salva il seguente manifest YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity: warning

    L'esempio precedente mostra come puoi specificare il bucket Cloud Storage in linea nel manifest del pod. L'esempio include i seguenti campi:

    • metadata.annotations: l'annotazione gke-gcsfuse/volumes: "true" è obbligatoria. Per le annotazioni facoltative, consulta Configurare le risorse per il contenitore sidecar.
    • spec.terminationGracePeriodSeconds: facoltativo. Per impostazione predefinita, il valore è 30. Se devi scrivere file di grandi dimensioni nel bucket Cloud Storage, aumenta questo valore per assicurarti che Cloud Storage FUSE abbia tempo sufficiente per svuotare la cache dei dati dopo l'uscita dell'applicazione. Per scoprire di più, consulta le best practice di Kubernetes: terminazione senza problemi.
    • spec.serviceAccountName: utilizza lo stesso ServiceAccount Kubernetes del passaggio Configurare l'accesso ai bucket Cloud Storage utilizzando la federazione delle identità per i carichi di lavoro di GKE per GKE.
    • spec.volumes[n].csi.driver: utilizza gcsfuse.csi.storage.gke.io come nome del driver CSI.
    • spec.volumes[n].csi.volumeAttributes.bucketName: specifica il nome del bucket Cloud Storage FUSE. Puoi specificare un'underscore (_) per montare tutti i bucket a cui può accedere il service account Kubernetes. Per saperne di più, consulta la sezione Montaggio dinamico nella documentazione di Cloud Storage FUSE.
    • spec.volumes[n].csi.volumeAttributes.mountOptions: facoltativo. Passa le opzioni di montaggio a Cloud Storage FUSE. Specifica i flag in una stringa separata da virgole, senza spazi.
    • spec.volumes[n].csi.volumeAttributes: facoltativo. Passare altri attributi del volume a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: facoltativo. Specifica true se tutti i mount del volume sono in sola lettura.
    • spec.containers[n].volumeMounts[m].readOnly: facoltativo. Specifica true se solo il montaggio di un volume specifico è di sola lettura.

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

Utilizza il volume dello spazio di archiviazione temporaneo CSI in un carico di lavoro del job

  1. Salva il seguente manifest YAML:

    apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example
  namespace: NAMESPACE
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never
  backoffLimit: 1

    Sostituisci quanto segue:

    Il manifest esegue il deployment di un job che utilizza un bucket Cloud Storage FUSE tramite un volume temporaneo CSI.

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

Se utilizzi il driver CSI in un workload Job o se il pod RestartPolicy è Never, il container sidecar uscirà automaticamente dopo l'uscita di tutti gli altri container del workload.

Per altri esempi, consulta la sezione Applicazioni di esempio nella documentazione del progetto GitHub.

Esegui il provisioning del volume utilizzando il provisioning statico

Con il provisioning statico, crei uno o più oggetti PersistentVolume (PV) contenenti i dettagli del sistema di archiviazione sottostante. I pod nei tuoi cluster possono quindi utilizzare lo spazio di archiviazione tramite PersistentVolumeClaims (PVC).

Crea un PersistentVolume

  1. Salva il seguente manifest YAML:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    Il manifest di esempio mostra come definire un PersistentVolume per i bucket Cloud Storage. L'esempio include i seguenti campi:

    • spec.csi.driver: utilizza gcsfuse.csi.storage.gke.io come nome del driver CSI.
    • spec.csi.volumeHandle: specifica il nome del bucket Cloud Storage. Puoi trasmettere un'underscore (_) per montare tutti i bucket a cui l'account di servizio Kubernetes è configurato per avere accesso. Per scoprire di più, consulta la sezione Montaggio dinamico nella documentazione di FUSE per Cloud Storage.
    • spec.mountOptions: facoltativo. Passa le opzioni di montaggio a Cloud Storage FUSE.
    • spec.csi.volumeAttributes: facoltativo. Passa gli attributi del volume a Cloud Storage FUSE.

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

Crea un PersistentVolumeClaim

  1. Salva il seguente manifest YAML:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: example-storage-class

    Il manifest di esempio mostra come definire un PersistentVolumeClaim per associare il PersistentVolume. L'esempio include i seguenti campi:

    • metadata.namespace: specifica il namespace PersistentVolumeClaim che deve essere coerente con il namespace del tuo carico di lavoro.

    Per associare un PersistentVolume a un PersistentVolumeClaim, assicurati di seguire queste linee guida:

    • I campi spec.storageClassName nei manifest PV e PVC devono corrispondere. storageClassName non deve fare riferimento a un oggetto StorageClass esistente. Per associare la rivendicazione a un volume, puoi utilizzare qualsiasi nome, ma non può essere vuoto.
    • I campi spec.accessModes nei manifest PV e PVC devono corrispondere.
    • spec.capacity.storage nel manifest PersistentVolume deve corrispondere spec.resources.requests.storage nel manifest PersistentVolumeClaim. Poiché i bucket Cloud Storage non hanno limiti di dimensione, puoi inserire un numero qualsiasi per la capacità, che però non può essere vuoto.

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

Utilizzare il volume da un PersistentVolumeClaim

  1. Salva il seguente manifest YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true

    L'esempio mostra come definire un pod che utilizza un bucket FUSE Cloud Storage tramite un'istanza PersistentVolumeClaim. L'esempio include i seguenti campi:

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

Per altri esempi, consulta la sezione Applicazioni di esempio nella documentazione del progetto GitHub.

Utilizzare i volumi con la memorizzazione nella cache dei file abilitata

Per impostazione predefinita, la funzionalità di memorizzazione nella cache dei file è disattivata su GKE. Per attivare e controllare la memorizzazione nella cache dei file, utilizza l'attributo volume fileCacheCapacity.

GKE utilizza un volume emptyDir per la memorizzazione nella cache dei file FUSE di Cloud Storage supportata dal disco di avvio della VM del nodo. Se attivi SSD locale sul nodo, GKE utilizza l'SSD locale per eseguire il backup del volume emptyDir.

Puoi configurare un volume della cache di lettura personalizzato per il contenitore sidecar per sostituire il volume emptyDir predefinito per la memorizzazione nella cache dei file nelle operazioni di lettura. Per le famiglie di VM CPU e GPU con supporto per le unità SSD locali, consigliamo di utilizzare lo spazio di archiviazione SSD locale. Per le famiglie TPU o Autopilot, consigliamo di utilizzare Balanced Persistent Disk o SSD Persistent Disk.

Utilizza un volume di archiviazione temporanea CSI con la memorizzazione nella cache dei file abilitata

Per eseguire il deployment di un pod che utilizza un bucket FUSE Cloud Storage tramite un volume effimero CSI con memorizzazione nella cache dei file:

  1. Crea un cluster o un pool di nodi con archiviazione temporanea basata su SSD locali.

    Segui la documentazione di GKE per creare un cluster o un pool di nodi con archiviazione temporanea basata su SSD locale.

  2. Salva il seguente manifest YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi"
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        fileCacheCapacity: "10Gi"

    Sostituisci quanto segue:

    Il contenitore di inizializzazione data-loader genera 1000 file di dimensioni pari a 64 KB e li carica in un bucket Cloud Storage. Il contenitore principale data-validator legge tutti i file dal bucket due volte e registra la durata.

  3. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

  4. Per visualizzare l'output del log, esegui il seguente comando:

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    Sostituisci NAMESPACE con lo spazio dei nomi del tuo carico di lavoro.

    L'output è simile al seguente:

    first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...

    L'output mostra che la seconda lettura con la cache locale è molto più rapida rispetto alla prima lettura con fallimento della cache.

Migliorare le prestazioni di lettura di file di grandi dimensioni utilizzando il download parallelo di Cloud Storage FUSE

Puoi utilizzare il download parallelo di Cloud Storage FUSE per accelerare la lettura di file di grandi dimensioni da Cloud Storage per i download multithread. Il download parallelo di Cloud Storage FUSE può essere particolarmente utile per i casi d'uso di pubblicazione di modelli con letture di dimensioni superiori a 1 GB.

Ecco alcuni esempi comuni:

  • Erogazione del modello, in cui è necessario un buffer di prefetch di grandi dimensioni per accelerare il download del modello durante l'avvio dell'istanza.
  • Ripristini dei punti di controllo, in cui è necessaria una cache di dati di sola lettura per migliorare l'accesso una tantum di più file di grandi dimensioni.
Best practice:

Utilizza il download parallelo per le applicazioni che eseguono letture di file di grandi dimensioni a thread singolo. Le applicazioni con un elevato parallelismo di lettura (che utilizzano più di otto thread) potrebbero riscontrare prestazioni inferiori con questa funzionalità.

Per utilizzare il download parallelo con il driver CSI di Cloud Storage FUSE, segui questi passaggi:

  1. Attiva la cache dei file. Crea un cluster con la memorizzazione nella cache dei file abilitata, come descritto in Utilizzare un volume di archiviazione effimero CSI con la memorizzazione nella cache dei file abilitata.

  2. Attiva il download parallelo. Nel file manifest, configura queste impostazioni aggiuntive utilizzando le opzioni di montaggio:

    1. Imposta file-cache:enable-parallel-downloads:true.
    2. Modifica file-cache:parallel-downloads-per-file, file-cache:max-parallel-downloads e file-cache:download-chunk-size-mb in base alle tue esigenze.

  3. (Facoltativo) Modifica gli attributi del volume. Se necessario, valuta la possibilità di modificare questi attributi del volume:

    • fileCacheForRangeRead per letture casuali o parziali.
    • metadataTypeCacheCapacity e metadataStatCacheCapacity per i carichi di lavoro di addestramento.

Fai clic su una di queste schede per scoprire come attivare il download parallelo, a seconda che tu stia utilizzando volumi di archiviazione temporanei o il provisioning statico:

Spazio di archiviazione temporanea

apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:parallel-downloads-per-file:4,file-cache:max-parallel-downloads:-1,file-cache:download-chunk-size-mb:3"
        fileCacheCapacity: "-1"

Provisioning statico

apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  mountOptions:
    - implicit-dirs
    - file-cache:enable-parallel-downloads:true
    - file-cache:parallel-downloads-per-file:4
    - file-cache:max-parallel-downloads:-1
    - file-cache:download-chunk-size-mb:3
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      fileCacheCapacity: "-1"
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

Configurare il montaggio dei bucket Cloud Storage FUSE

Questa sezione descrive come configurare i volumi Cloud Storage FUSE.

Opzioni di montaggio

Il driver CSI di Cloud Storage FUSE supporta le opzioni di montaggio per configurare il modo in cui i bucket Cloud Storage vengono montati sul file system locale. Per un elenco completo delle opzioni di montaggio supportate, consulta la documentazione della CLI gcsfuse.

Puoi specificare i flag di montaggio nei seguenti modi:

  • Nel campo spec.mountOptions di un file manifest PersistentVolume, se utilizzi il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes.mountOptions, se utilizzi i volumi effimeri CSI.

Attributi del volume

Il driver CSI di Cloud Storage FUSE non ti consente di specificare direttamente il file di configurazione di Cloud Storage FUSE. Puoi configurare alcuni dei campi nel file di configurazione utilizzando i seguenti attributi del volume. I valori vengono tradotti nei campi del file di configurazione.

  • gcsfuseLoggingSeverity

    • Descrizione: la gravità dei log che vuoi che Cloud Storage FUSE generi, expressed as an enum. Questo attributo del volume viene tradotto nel campo del file di configurazione logging:severity.

    • Valori validi (ordinati dalla gravità più bassa a quella più alta):

      • trace
      • debug
      • info
      • warning
      • error

    • Valore predefinito: info.

  • fileCacheCapacity

    • Descrizione: le dimensioni massime che la cache dei file può utilizzare. Se è presente un valore diverso da zero, questo attributo del volume attiva la memorizzazione nella cache dei file in Cloud Storage FUSE. Questo attributo del volume viene tradotto nel campo del file di configurazione file-cache:max-size-mb.

    • Valori validi:

      • Valori Quantità, ad esempio: 500Mi, 10Gi.
      • "-1": per utilizzare l'intera capacità disponibile del volume della cache.
      • "0": la cache dei file è disattivata.

    • Valore predefinito: "0".

  • fileCacheForRangeRead

    • Descrizione: indica se l'oggetto completo deve essere scaricato in modo asincrono e archiviato nella directory della cache di Cloud Storage FUSE quando viene eseguita la prima lettura da un offset diverso da zero. Questo valore deve essere impostato su "true" se prevedi di eseguire diverse letture casuali o parziali. Questo attributo del volume viene tradotto nel campo del file di configurazione file-cache:cache-file-for-range-read.

    • Valori validi:

      • Valori booleani in formato stringa: "true", "false".

    • Valore predefinito: "false".

  • metadataStatCacheCapacity

    • Descrizione: la dimensione massima che la cache delle statistiche può utilizzare. La cache delle statistiche viene sempre mantenuta interamente in memoria. Se utilizzi già l'opzione di montaggio stat-cache-capacity, il valore verrà comunque rispettato e tradotto in modo appropriato in questa nuova configurazione. Questo attributo del volume viene tradotto nel campo del file di configurazione metadata-cache:stat-cache-max-size-mb.

    • Valori validi:

      • Valori Quantità, ad esempio: 500Mi, 1Gi.
      • "-1": per consentire alla cache delle statistiche di utilizzare tutta la memoria necessaria.
      • "0": la cache delle statistiche è disattivata.
      • Utilizza il valore predefinito 32Mi se il tuo carico di lavoro prevede fino a 20.000 file. Se il tuo carico di lavoro è costituito da più di 20.000 file, aumenta le dimensioni di 10 MiB per ogni 6000 file aggiuntivi, ovvero in media circa 1500 byte per file.

    • Valore predefinito: 32Mi.

  • metadataTypeCacheCapacity

    • Descrizione: le dimensioni massime per directory che la cache dei tipi può utilizzare. La cache dei tipi viene sempre mantenuta interamente in memoria. Questo attributo del volume viene tradotto nel campo del file di configurazione metadata-cache:type-cache-max-size-mb.

    • Valori validi:

      • Valori Quantità, ad esempio: 500Mi, 1Gi.
      • "-1": per consentire alla cache dei tipi di utilizzare tutta la memoria necessaria.
      • "0": la cache dei tipi è disattivata.
      • Utilizza il valore predefinito 4Mi se il numero massimo di file all'interno di una singola directory del bucket che stai montando non supera i 20.000 file. Se il numero massimo di file all'interno di un'unica directory che stai montando contiene più di 20.000 file, aumenta le dimensioni di 1 MiB per ogni 5000 file, ovvero in media circa 200 byte per file.

    • Valore predefinito: 4Mi.

  • metadataCacheTTLSeconds

    • Descrizione: la durata (TTL), in secondi, delle voci dei metadati memorizzati nella cache. Se utilizzi già le opzioni di montaggio stat-cache-ttl o type-cache-ttl, i valori verranno comunque rispettati e tradotti in modo appropriato in questa nuova configurazione. Questo attributo del volume viene tradotto nel campo del file di configurazione metadata-cache:ttl-secs.

    • Valori validi:

      • Valori interi in formato stringa, ad esempio: "600".
      • "-1": ignora la scadenza TTL e pubblica il file dalla cache ogni volta che è disponibile.
      • "0": assicurati che venga letto il file più aggiornato. Se utilizzi un valore 0, viene eseguita una chiamata ai metadati Get per assicurarti che la generazione di oggetti per il file nella cache corrisponda a quanto archiviato in Cloud Storage.

    • Valore predefinito: "60".

Puoi specificare gli attributi del volume nei seguenti modi:

  • Nel campo spec.csi.volumeAttributes di un file manifest PersistentVolume, se utilizzi il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes, se utilizzi i volumi effimeri CSI.

Considerazioni

Tieni presenti le seguenti considerazioni quando configuri i supporti:

  • I seguenti flag non sono consentiti: app-name, temp-dir, foreground, log-file, log-format, key-file, token-url e reuse-token-from-url.
  • Cloud Storage FUSE non rende visibili le directory implicite per impostazione predefinita. Per visualizzare queste directory, puoi attivare il flag di montaggio implicit-dirs. Per saperne di più, consulta File e directory nella documentazione di GitHub di Cloud Storage FUSE.
  • Se utilizzi un contesto di sicurezza per il pod o il container o se l'immagine del container utilizza un gruppo o un utente non root, devi impostare i flag di montaggio uid e gid. Devi anche utilizzare i flag di montaggio file-mode e dir-mode per impostare le autorizzazioni del file system. Tieni presente che non puoi eseguire i comandi chmod, chown o chgrp su un sistema di file FUSE di Cloud Storage, pertanto i flag di montaggio uid, gid, file-mode e dir-mode sono necessari per fornire l'accesso a un utente o gruppo non root.
  • Se vuoi montare solo una directory nel bucket anziché l'intero bucket, passa il percorso relativo della directory utilizzando il flag only-dir=relative/path/to/the/bucket/root.
  • Per ottimizzare il comportamento della memorizzazione nella cache di Cloud Storage FUSE, configura gli attributi del volume. Per maggiori dettagli, consulta la documentazione relativa alla memorizzazione nella cache FUSE di Cloud Storage.
  • Se devi specificare un numero massimo di connessioni TCP consentite per server, puoi specificare questo valore massimo utilizzando il flag max-conns-per-host. Il numero massimo di connessioni TCP che definisci diventa effettivo quando --client-protocol è impostato su http1. Il valore predefinito è 0, che indica che non esiste un limite per le connessioni TCP (limitato dalle specifiche della macchina).
  • Se devi configurare le opzioni di montaggio del kernel Linux, puoi passare le opzioni utilizzando il flag o. Ad esempio, se non vuoi consentire l'esecuzione diretta di eventuali file binari sul file system montato, imposta il flag o=noexec. Ogni opzione richiede un flag separato, ad esempio o=noexec,o=noatime. Sono consentite solo le seguenti opzioni: exec, noexec, atime, noatime, sync, async e dirsync.
  • Se devi risolvere i problemi di Cloud Storage FUSE, imposta il flag log-severity su TRACE. Quindi, l'attributo del volume gcsfuseLoggingSeverity viene impostato automaticamente su trace.
  • Il driver CSI di Cloud Storage FUSE non ti consente di modificare il campo cache-dir nel file di configurazione di Cloud Storage FUSE, utilizza l'attributo del volume fileCacheCapacity per attivare o disattivare la memorizzazione nella cache dei file. Per sostituire il volume emptyDir predefinito per la memorizzazione nella cache dei file, puoi configurare un volume della cache personalizzato per il contenitore sidecar.

Metriche di Cloud Storage FUSE

Le seguenti metriche di Cloud Storage FUSE sono ora disponibili tramite l'API di monitoraggio GKE. I dettagli sulle metriche di Cloud Storage FUSE, come etichette, tipo e unità, sono disponibili in Metriche di sistema GKE. Queste metriche sono disponibili per ogni pod che utilizza Cloud Storage FUSE e ti consentono di configurare gli approfondimenti per volume e bucket.

Metriche del file system

Le metriche del file system monitorano le prestazioni e lo stato del file system, inclusi il numero di operazioni, gli errori e la velocità di esecuzione. Queste metriche possono aiutarti a identificare i colli di bottiglia e ottimizzare le prestazioni.

  • gcsfusecsi/fs_ops_count
  • gcsfusecsi/fs_ops_error_count
  • gcsfusecsi/fs_ops_latency

Metriche di Cloud Storage

Puoi monitorare le metriche di Cloud Storage, tra cui volume dei dati, velocità e attività di richiesta, per capire in che modo le tue applicazioni interagiscono con i bucket Cloud Storage. Questi dati possono aiutarti a identificare le aree di ottimizzazione, ad esempio migliorare i pattern di lettura o ridurre il numero di richieste.

  • gcsfusecsi/gcs_download_bytes_count
  • gcsfusecsi/gcs_read_count
  • gcsfusecsi/gcs_read_bytes_count
  • gcsfusecsi/gcs_reader_count
  • gcsfusecsi/gcs_request_count
  • gcsfusecsi/gcs_request_latencies

Metriche della cache dei file

Puoi monitorare le metriche della cache dei file, tra cui il volume di lettura dei dati, la velocità e il tasso di successo della cache, per ottimizzare Cloud Storage FUSE e le prestazioni dell'applicazione. Analizza queste metriche per migliorare la tua strategia di memorizzazione nella cache e massimizzare gli hit della cache.

  • gcsfusecsi/file_cache_read_bytes_count
  • gcsfusecsi/file_cache_read_latencies
  • gcsfusecsi/file_cache_read_count

Disabilitare il driver CSI di Cloud Storage FUSE

Non puoi disattivare il driver CSI di Cloud Storage FUSE nei cluster Autopilot.

Puoi disattivare il driver CSI di Cloud Storage FUSE in un cluster standard esistente utilizzando Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Sostituisci CLUSTER_NAME con il nome del cluster.

Risoluzione dei problemi

Per risolvere i problemi relativi all'utilizzo del driver CSI FUSE Cloud Storage, consulta la Guida alla risoluzione dei problemi nella documentazione del progetto GitHub.

Passaggi successivi