Accedi 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é utilizzare API specifiche per il cloud.

Il driver CSI di Cloud Storage FUSE ti consente di utilizzare 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 Volumi supportati da 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 dischi permanenti, in base alle tue esigenze di prezzo e prestazioni. Devi attivare l'opzione per abilitare la memorizzazione nella cache dei file con il driver CSI di Cloud Storage FUSE. Per scoprire di più sulle best practice per la memorizzazione nella cache, consulta Prestazioni 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 su Standard Autopilot.
  • Il driver CSI di Cloud Storage FUSE non necessita di un accesso privilegiato, come richiesto dai client FUSE. Ciò consente una migliore strategia di sicurezza.
  • 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 ReadWriteMany, ReadOnlyMany, e le modalità di accesso 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. Quando si utilizza la federazione delle identità per i carichi di lavoro, è richiesto un accesso uniforme a livello di bucket per i carichi di lavoro di lettura e scrittura.
  • Se esegui l'addestramento e la gestione dei carichi di lavoro ML con framework come Ray, PyTorch, Spark e TensorFlow: portabilità e semplicità forniti dal driver CSI di Cloud Storage FUSE, puoi eseguire i carichi di lavoro direttamente sui tuoi cluster GKE senza ulteriori modifiche al codice.
  • Puoi leggere oggetti Cloud Storage con la memorizzazione nella cache dei file abilitata per migliorare le prestazioni di lettura. La memorizzazione nella cache dei file accelera le letture ripetute, per la distribuzione di 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 v.2.4.0 e la cache dei file abilitata, puoi utilizzare il download parallelo per velocizzare la lettura di file di grandi dimensioni da Cloud Storage per i download multi-thread. Puoi usare questa funzionalità per migliorare i tempi di caricamento del modello, in particolare per letture superiori a 1 GB (ad esempio, fino al doppio della velocità durante il caricamento di Llama2 70B).
  • Puoi utilizzare volumi Cloud Storage FUSE in container init.
  • Puoi visualizzare insight sulle metriche per Cloud Storage FUSE, inclusi l'utilizzo del file system, di Cloud Storage e della cache di file.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

  • 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 abilitata, 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 GKE. Devi selezionare 1.24 o versioni successive.
  • LOCATION: la località 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 abilitato il driver CSI di Cloud Storage FUSE, puoi utilizzarlo in Volumi Kubernetes specificando il nome del driver e del provisioner: gcsfuse.csi.storage.gke.io.

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

Per rendere i bucket Cloud Storage accessibili 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 Compute Engine per il cluster.

  2. Crea uno spazio dei nomi da utilizzare per Kubernetes ServiceAccount. Puoi anche utilizza 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 Kubernetes ServiceAccount.

  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 tuo nuovo account di servizio 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 ServiceAccount Kubernetes solo accedi a un bucket Cloud Storage specifico utilizzando il comando seguente:

    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 la sezione Identificazione dei progetti.
    • PROJECT_ID: l'ID del progetto del tuo cluster GKE.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per Kubernetes ServiceAccount.
    • KSA_NAME: il nome del nuovo service account Kubernetes.
    • ROLE_NAME: il ruolo IAM da assegnare all'account di servizio di 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 e scrittura, utilizza il ruolo Utente oggetti Storage (roles/storage.objectUser).

    Facoltativamente, puoi concedere il ruolo al tuo ServiceAccount 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 Kubernetes ServiceAccount.
    • KSA_NAME: il nome del nuovo service account Kubernetes.
    • ROLE_NAME: il ruolo IAM da assegnare all'account di servizio di 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 e scrittura, utilizza il ruolo Utente oggetti Storage (roles/storage.objectUser).

Preparati a montare i bucket Cloud Storage FUSE

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

Specifica le annotazioni dei 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 container collaterale e montare i bucket Cloud Storage per il 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 tuoi volumi supportati da Cloud Storage essere consumato da altri tipi di carichi di lavoro Kubernetes (ad esempio, Job, Deployment oppure 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 container collaterale

Per impostazione predefinita, il container collaterale è configurato con le seguenti richieste di risorse: con limiti di risorse non impostati (per 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

Per decidere la quantità di risorse da allocare, tieni presente quanto segue:

  • Se imposti solo una delle annotazioni relative alla richiesta o ai limiti di risorse, GKE Autopilot applica gli stessi valori per la richiesta e il limite di risorse.
  • Se il pod del carico di lavoro utilizza più volumi Cloud Storage, il file collaterale le risorse del container sono condivise da più istanze Cloud Storage FUSE. 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 un throughput più elevato, alloca più CPU al contenitore sidecar. Una CPU insufficiente causerà il throttling di Cloud Storage FUSE.
  • Se i carichi di lavoro devono elaborare un numero elevato di file e Cloud Storage FUSE memorizzazione nella cache dei metadati è abilitata, aumenta l'allocazione della memoria del container collaterale. Il consumo di memoria di Cloud Storage FUSE per la memorizzazione nella cache dei metadati è proporzionale il numero di file, ma non le loro dimensioni. Una memoria insufficiente causerà errori di esaurimento della memoria di Cloud Storage FUSE e l'arresto anomalo dell'applicazione del carico di lavoro.
  • Per la memorizzazione nella cache dei file, Cloud Storage FUSE memorizza nella cache i file per impostazione predefinita in una directory temporanea locale. Stima quanto spazio libero richiede il tuo carico di lavoro di memorizzazione nella cache e aumenta di conseguenza il limite di spazio di archiviazione temporaneo. Per scoprire 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 di spazio libero necessario al carico di lavoro per la gestione temporanea durante la scrittura file di grandi dimensioni e aumenta il limite di spazio di archiviazione temporaneo di conseguenza. Per scoprire di più, consulta la sezione semantica di lettura/scrittura. nella documentazione GitHub di Cloud Storage FUSE.
  • Puoi utilizzare il valore "0" per annullare l'impostazione di limiti di risorse o richieste 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. È utile quando non puoi decidere l'importo di risorse di cui Cloud Storage FUSE ha bisogno per i tuoi carichi di lavoro e vuoi che Cloud Storage FUSE e consumano 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 limiti appropriati.

Configura un'immagine privata per il contenitore sidecar

Questa sezione descrive come utilizzare l'immagine container collaterale se ospiti in un Container Registry privato. Questo scenario potrebbe essere applicabile se devi utilizzare cluster privati per motivi di sicurezza o se il tuo cluster ha accesso limitato alla rete internet pubblica. Per configurare e utilizzare l'immagine container del sidecar privato, segui questi passaggi:

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

  2. Esegui il pull nel tuo ambiente locale ed eseguine il push al Container Registry privato.

  3. Nel file manifest, specifica un contenitore denominato gke-gcsfuse-sidecar con solo il campo image. GKE utilizzerà il file collaterale specificato dell'immagine container per prepararsi all'inserimento del container collaterale. Ecco un esempio:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Sostituisci quanto segue:

  • PRIVATE_REGISTRY: il tuo Container Registry privato.
  • PRIVATE_IMAGE_TAG: il tuo container sidecar privato .

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

Questa sezione descrive come configurare un volume di 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 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 GiB su 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 fsGroup.
  • BUFFER_VOLUME_PVC: il nome predefinito dell'oggetto PVC.

Configura un volume personalizzato della cache di lettura per il container collaterale

Questa sezione descrive come configurare un volume di cache personalizzato per la memorizzazione nella cache di lettura di Cloud Storage FUSE. Questo scenario potrebbe verificarsi se devi sostituire quello predefinito Volume emptyDir 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 un volume della cache personalizzato, devi specificare un valore fsGroup diverso da zero. L'esempio seguente mostra come utilizzare una PVC predefinita 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 del PVC predefinito.

Esegui il provisioning del tuo 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. Consulta Configurazione delle risorse per il container collaterale per annotazioni facoltative.
    • 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 Cloud Storage FUSE ha tempo sufficiente per il flush dei dati dopo l'applicazione esce. 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: usa 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 trattino basso (_) per montare tutti bucket a cui Kubernetes ServiceAccount può accedere. 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. Passa ad altro attributi di 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 di archiviazione temporanea CSI in un carico di lavoro di un 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 FUSE Cloud Storage 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 carico di lavoro Job o se il pod RestartPolicy è Never, il container collaterale uscirà automaticamente dopo tutti gli altri vengono chiusi i container dei carichi di lavoro.

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 PersistentVolumeClaim (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

    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 passare un'underscore (_) per montare tutti i bucket a cui l'account di servizio Kubernetes è configurato per avere accesso. Per ulteriori informazioni, vedi Montaggio dinamico nella documentazione di Cloud Storage FUSE.
    • 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
  volumeName: gcs-fuse-csi-pv
  storageClassName: example-storage-class

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

    • metadata.namespace: specifica lo spazio dei nomi PersistentVolumeClaim coerente con lo spazio dei nomi del carico di lavoro.
    • spec.volumeName: specifica il nome del PersistentVolume.

    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 sul manifest del PersistentVolume deve corrispondere spec.resources.requests.storage sul manifest di 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.

Consuma i tuoi volumi con la memorizzazione nella cache dei file abilitata

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

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

Puoi configurare un volume personalizzato della cache di lettura per il container collaterale. 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 memorizzazione nella cache dei file abilitata

esegui il deployment di un pod che utilizza un bucket Cloud Storage FUSE tramite un volume temporaneo CSI. con la memorizzazione nella cache dei file, segui questi passaggi:

  1. Crea un cluster o un pool di nodi con archiviazione temporanea supportata da SSD locali.

    Segui la documentazione di GKE per creare un cluster o un pool di nodi con archiviazione temporanea supportata da SSD locali.

  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 questo 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 un mancato hit della cache.

Migliora le prestazioni di lettura dei 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 per gestire casi d'uso con letture 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.
  • Ripristino dei checkpoint, per cui è necessaria una cache dei dati di sola lettura per migliorare accesso una tantum a 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 temporaneo CSI con la memorizzazione nella cache dei file abilitata.

  2. Abilita 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 secondo necessità.

  3. (Facoltativo) Ottimizza 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 vedere come attivare il download parallelo a seconda che tu stia utilizzando volumi di archiviazione temporanei o del provisioning:

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"

Configura il modo in cui vengono montati i 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 la modalità I bucket Cloud Storage sono montati sul file system locale. Per per l'elenco completo delle opzioni di montaggio supportate, vedi consulta la documentazione sull'interfaccia a riga di comando 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 e usare i volumi temporanei CSI.

Attributi del volume

Il driver CSI di Cloud Storage FUSE non 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 convertiti nei campi del file di configurazione.

  • gcsfuseLoggingSeverity

    • Descrizione: la gravità dei log che vuoi che vengano generati da Cloud Storage FUSE. espresso come enum. Se usi già debug_fuse, debug_fs, o debug_gcs, questa nuova configurazione verrà impostata automaticamente su trace. Questo attributo del volume viene convertito 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 un valore diverso da zero questo attributo di volume consente 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:

      • i valori Quantità, ad esempio 500Mi, 10Gi.
      • "-1": per utilizzare l'intera capacità disponibile del volume di 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 convertito 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 è sempre interamente conservata in memoria. Se usi già l'opzione di montaggio stat-cache-capacity, il valore sarà comunque rispettato e verrà 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 carico di lavoro riguarda fino a 20.000 file. Se il 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: la dimensione massima per directory che il tipo di cache 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:

      • i 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 in un la singola directory del bucket che stai montando contiene al massimo 20.000 file. Se il numero massimo di file all'interno di una singola directory che stai montando contiene più di 20.000 file, aumenta la dimensione di 1 MiB ogni 5000 file, 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 usi già le opzioni di montaggio stat-cache-ttl o type-cache-ttl, i valori continueranno a essere rispettati e verranno 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 una scadenza TTL e pubblica il file dalla cache ogni volta che è disponibile.
      • "0": assicura 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 manifest PersistentVolume, se il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes, se utilizzi i volumi effimeri CSI.

Considerazioni

Tieni presente le seguenti considerazioni quando configuri i montaggi:

  • 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. A rendi visibili queste directory, puoi attivare il flag di montaggio implicit-dirs. Per saperne di più, consulta la sezione 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 utilizzare anche file-mode e dir-mode monta i flag 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 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 sulla memorizzazione nella cache di Cloud Storage FUSE.
  • Se devi specificare il numero massimo di connessioni TCP consentite per server, puoi specificare questo numero 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 nessun limite per le connessioni TCP (limitate 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 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 problemi di Cloud Storage FUSE, imposta debug_fuse, debug_fs e debug_gcs. Se viene specificata una delle tre opzioni, 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 container collaterale.

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 aiutare a identificare i colli di bottiglia e a 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 di dati, velocità e attività delle richieste, 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 relative alla 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 hit 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 i successi della cache.

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

Disabilita il driver CSI di Cloud Storage FUSE

Non puoi disabilitare 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 la CLI Google Cloud.

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

Sostituisci CLUSTER_NAME con il nome del tuo 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