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

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

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

Il driver supporta in modo nativo i seguenti modi per configurare i volumi supportati da Cloud Storage:

Puoi utilizzare il driver CSI di Cloud Storage FUSE con la memorizzazione dei file nella cache per migliorare le prestazioni di lettura delle applicazioni che gestiscono file di piccole dimensioni dai bucket Cloud Storage. La funzionalità di cache dei file di Cloud Storage FUSE è una cache di lettura basata su client che consente di gestire più rapidamente le letture ripetute dei file dall'archiviazione della cache scelta da te. Puoi scegliere tra una gamma di opzioni di archiviazione per la cache di lettura, inclusi SSD locali e archiviazione basata su Persistent Disk, in base alle tue esigenze di rapporto prezzo/prestazioni. Devi attivare l'opzione per abilitare la memorizzazione nella cache dei file con il driver CSI di Cloud Storage FUSE. Per saperne di più sulle best practice per la memorizzazione nella cache, consulta Prestazioni e best practice di Cloud Storage FUSE.

Vantaggi

  • Il driver CSI di Cloud Storage FUSE sul tuo cluster attiva il deployment e la gestione automatici del driver. Il driver funziona sia su cluster Standard che su Autopilot.
  • Il driver CSI di Cloud Storage FUSE non richiede l'accesso privilegiato in genere richiesto dai client FUSE. Ciò consente una migliore strategia di sicurezza.
  • Il supporto dei volumi temporanei 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 sul modo in cui i 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 di carichi di lavoro ML con framework come Ray, PyTorch, Spark e TensorFlow, la portabilità e la semplicità del driver CSI di Cloud Storage FUSE ti consentono di eseguire i carichi di lavoro direttamente sui tuoi cluster GKE senza ulteriori modifiche al codice.
  • Puoi leggere oggetti Cloud Storage con memorizzazione nella cache dei file abilitata per migliorare le prestazioni di lettura. Per saperne di più sui vantaggi della memorizzazione nella cache dei file, consulta la documentazione di Cloud Storage FUSE.
  • Puoi consumare volumi Cloud Storage FUSE in container init.

Prima di iniziare

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

  • Abilita l'API Google Kubernetes Engine.
    • Abilita l'API Google Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installa e quindi initialize 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 un'area geografica in cui è in esecuzione il 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 abilitato, 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 la versione 1.24 o successiva.
  • LOCATION: la località di Compute Engine per il cluster.
  • PROJECT_ID: il tuo ID progetto.

Per abilitare il driver su 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 nei 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. Richiedi 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 località di Compute Engine per il cluster.

  2. Crea uno spazio dei nomi da utilizzare per Kubernetes ServiceAccount. 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 l'account di servizio Kubernetes.

  3. Crea un ServiceAccount Kubernetes da utilizzare per l'applicazione. Puoi anche utilizzare qualsiasi ServiceAccount Kubernetes esistente in qualsiasi spazio dei nomi, incluso defaultKubernetes ServiceAccount.

    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 l'account di servizio Kubernetes.

  4. Concedi uno dei ruoli IAM per Cloud Storage all'account di servizio Kubernetes.

    Puoi concedere il ruolo all'account di servizio Kubernetes per accedere solo a uno specifico bucket Cloud Storage 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 progetto del tuo cluster GKE.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per l'account di servizio Kubernetes.
    • KSA_NAME: il nome del tuo nuovo account di servizio Kubernetes.
    • ROLE_NAME: il ruolo IAM da assegnare all'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 e scrittura, utilizza il ruolo Utente oggetti Storage (roles/storage.objectUser).

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

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

Preparati a montare i bucket Cloud Storage FUSE

Questa sezione illustra come preparare il montaggio dei bucket Cloud Storage FUSE sui cluster.

Specifica le annotazioni dei pod

Il driver CSI si basa sulle annotazioni dei pod per identificare se il tuo pod utilizza volumi supportati da Cloud Storage. Se il driver rileva le annotazioni necessarie, inserisce un container collaterale chiamato gke-gcsfuse-sidecar nel pod del carico di lavoro. Le istanze Cloud Storage FUSE vengono eseguite all'interno del container collaterale e montano 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 volumi supportati da 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.

Configura le risorse per il container collaterale

Per impostazione predefinita, il container collaterale è configurato con le seguenti richieste di risorse, con i limiti delle risorse non impostati:

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

Per sovrascrivere questi valori, puoi specificare l'annotazione gke-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 alle richieste o ai limiti di risorse, GKE applica gli stessi valori per la richiesta e il limite di risorse.
  • Se il pod del carico di lavoro utilizza più volumi Cloud Storage, le risorse container collaterali vengono condivise da più istanze Cloud Storage FUSE. Se questo è il tuo caso, valuta la possibilità di aumentare l'allocazione delle risorse per più volumi di Cloud Storage.
  • Alloca più CPU al container collaterale se i tuoi carichi di lavoro hanno bisogno di una velocità effettiva maggiore. Una CPU insufficiente causerà la limitazione di Cloud Storage FUSE.
  • Se i carichi di lavoro devono elaborare un numero elevato di file e la memorizzazione dei metadati di Cloud Storage FUSE è 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 al numero di file, ma non alle loro dimensioni. Una memoria insufficiente causerà errori di esaurimento della memoria di Cloud Storage FUSE e comporterà l'arresto anomalo dell'applicazione del carico di lavoro.
  • Per la memorizzazione nella cache di file, Cloud Storage FUSE memorizza per impostazione predefinita i file in una directory temporanea locale. Stima lo spazio libero necessario al carico di lavoro per la memorizzazione nella cache di file e aumenta di conseguenza il limite di archiviazione temporanea. Per scoprire di più, consulta gli attributi del volume.
  • Per le operazioni di scrittura, per impostazione predefinita Cloud Storage FUSE posiziona i file in una directory temporanea locale prima che vengano caricati nel bucket Cloud Storage. Stima la quantità di spazio libero necessario al tuo carico di lavoro per la gestione temporanea quando scrivi file di grandi dimensioni e aumenta di conseguenza il limite di archiviazione temporanea. Per saperne di più, consulta la sezione Lettura/scrittura della semantica 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 container collaterale con la richiesta di memoria predefinita. Ciò è utile quando non puoi decidere la quantità di risorse necessarie a Cloud Storage FUSE per i tuoi carichi di lavoro e vuoi che Cloud Storage FUSE utilizzi tutte le risorse disponibili su un nodo. Dopo aver calcolato i requisiti delle risorse per Cloud Storage FUSE in base alle metriche dei carichi di lavoro, puoi impostare limiti appropriati.

Configura un'immagine privata per il container collaterale

Questa sezione descrive come utilizzare l'immagine container collaterale se la ospiti in un Container Registry privato. Questo scenario potrebbe verificarsi se devi utilizzare cluster privati per motivi di sicurezza o se il 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 container collaterale pubblica compatibile.

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

  3. Nel file manifest, specifica un container denominato gke-gcsfuse-sidecar con solo il campo image. GKE userà l'immagine container collaterale specificata per l'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 tag immagine container del tuo sidecar privato.

Configura un volume del buffer di scrittura personalizzato per il container collaterale

Questa sezione descrive come configurare un volume di buffer personalizzato per il buffering di scrittura di Cloud Storage FUSE. Questo scenario potrebbe verificarsi se devi sostituire il volume emptyDir predefinito per consentire a Cloud Storage FUSE di organizzare i file nelle operazioni di scrittura. Puoi specificare qualsiasi tipo di spazio di archiviazione supportato da GKE, ad esempio PersistentVolumeClaim, e GKE utilizzerà il volume specificato per il buffering di 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 una PVC predefinita 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 il volume emptyDir predefinito per consentire a Cloud Storage FUSE di memorizzare nella cache i file nelle operazioni di lettura. Puoi specificare qualsiasi tipo di spazio di archiviazione supportato da GKE, ad esempio PersistentVolumeClaim, e GKE utilizzerà il volume specificato per la memorizzazione nella cache dei file. Questo è utile se devi memorizzare nella cache file più grandi di 10 GiB su cluster Autopilot. Per utilizzare il 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 predefinito dell'oggetto PVC.

Esegui il provisioning del tuo volume come volume temporaneo CSI

I volumi temporanei CSI supportati dai bucket Cloud Storage sono legati al ciclo di vita dei pod. Con questo approccio al provisioning, non è necessario mantenere gli oggetti PersistentVolume e PersistentVolumeClaim associati ai bucket Cloud Storage dopo la terminazione del pod.

Consuma il volume di archiviazione temporanea 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 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 Configurare le risorse per il container collaterale per le annotazioni facoltative.
    • spec.terminationGracePeriodSeconds: facoltativo. Il valore predefinito è 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 lo svuotamento dei dati dopo l'uscita dell'applicazione. Per saperne di più, vedi Best practice di Kubernetes: chiusura con tolleranza.
    • spec.serviceAccountName: utilizza lo stesso account di servizio Kubernetes del passaggio Configurare l'accesso ai bucket Cloud Storage utilizzando la federazione delle identità per i carichi di lavoro 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 i bucket a cui può accedere l'account di servizio Kubernetes. Per ulteriori informazioni, consulta 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 separati da virgole, senza spazi.
    • spec.volumes[n].csi.volumeAttributes: facoltativo. Passa altri attributi di volume a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: facoltativo. Specifica true se tutti i montaggi del volume sono di sola lettura.
    • spec.containers[n].volumeMounts[m].readOnly: facoltativo. Specifica true se solo un montaggio specifico del volume è 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 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 carico di lavoro Job o se il pod RestartPolicy è Never, il container collaterale verrà chiuso automaticamente dopo l'uscita di tutti gli altri container del carico 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, puoi creare uno o più oggetti PersistentVolume (PV) contenenti i dettagli del sistema di archiviazione sottostante. I pod nei tuoi cluster possono quindi consumare 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

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

    • spec.csi.driver: usa gcsfuse.csi.storage.gke.io come nome del driver CSI.
    • spec.csi.volumeHandle: specifica il nome del bucket Cloud Storage. Puoi passare un trattino basso (_) per montare tutti i bucket a cui è configurato l'account di servizio Kubernetes. 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 di 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 PersistentVolumeClaim per associare il PersistentVolume. L'esempio include i seguenti campi:

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

    Per associare un PersistentVolume a un PersistentVolumeClaim, segui 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 dichiarazione a un volume, puoi usare il nome che preferisci, ma il campo non può essere vuoto.
    • I campi spec.accessModes nei manifest PV e PVC devono corrispondere.
    • spec.capacity.storage nel manifest del PersistentVolume deve corrispondere a spec.resources.requests.storage nel manifest di PersistentVolumeClaim. Poiché i bucket Cloud Storage non hanno limiti di dimensione, puoi inserire un numero qualsiasi per la capacità, ma non può essere vuoto.

  2. Applica il manifest al cluster:

    kubectl apply -f FILE_PATH

    Sostituisci FILE_PATH con il percorso del file YAML.

utilizza 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 Cloud Storage FUSE tramite un 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 su GKE. Per attivare e controllare la memorizzazione nella cache dei file, utilizza l'attributo del volume fileCacheCapacity.

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

Puoi configurare un volume personalizzato della cache di lettura per il container collaterale al fine di sostituire il volume emptyDir predefinito per la memorizzazione nella cache dei file nelle operazioni di lettura. Per le famiglie di VM con CPU e GPU che supportano gli SSD locali, consigliamo di utilizzare lo spazio di archiviazione SSD locale. Per le famiglie TPU o Autopilot, consigliamo di utilizzare un disco permanente bilanciato o un disco permanente SSD.

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

Per eseguire il deployment di un pod che utilizza un bucket Cloud Storage FUSE tramite un volume temporaneo CSI con 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
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  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 container di init data-loader genera 1000 file di dimensioni pari a 64 KiB e li carica in un bucket Cloud Storage. Il container principale data-validator legge due volte tutti i file del bucket 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ù veloce della prima con fallimento della cache.

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 il modo in cui i bucket Cloud Storage vengono montati sul file system locale. Per l'elenco completo delle opzioni di montaggio supportate, consulta la documentazione dell'interfaccia a riga di comando gcsfuse.

Puoi specificare i flag di montaggio nei seguenti modi:

  • Nel campo spec.mountOptions di un manifest PersistentVolume, se utilizzi il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes.mountOptions, se utilizzi 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 campi nel file di configurazione utilizzando i seguenti attributi di volume. I valori vengono convertiti nei campi del file di configurazione.

  • gcsfuseLoggingSeverity

    • Descrizione: la gravità dei log che vuoi generare con Cloud Storage FUSE, espressa come enum. Se utilizzi già le opzioni di montaggio debug_fuse, debug_fs o debug_gcs, questa nuova configurazione verrà impostata automaticamente su trace. 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: la dimensione massima utilizzabile dalla cache dei file. Se è presente 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:

      • Valori di Quantità, ad esempio: 500Mi, 10Gi.
      • "-1": per utilizzare l'intera capacità disponibile del volume di cache.
      • "0": la cache del 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 la prima lettura viene eseguita da un offset diverso da zero. Dovrebbe essere impostato su "true" se prevedi di eseguire diverse letture casuali o letture 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 utilizzabile dalla cache delle statistiche. La cache delle statistiche è sempre interamente conservata in memoria. Se stai già utilizzando 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 di Quantità, ad esempio: 500Mi, 1Gi.
      • "-1": per consentire alla cache delle statistiche di utilizzare la memoria necessaria.
      • "0": la cache delle statistiche è disabilitata.
      • Utilizza il valore predefinito 32Mi se il carico di lavoro riguarda fino a 20.000 file. Se il carico di lavoro supera i 20.000 file, aumenta la dimensione in base a valori di 10 MiB per ogni 6000 file aggiuntivi, 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 è sempre interamente conservata in memoria. Questo attributo del volume viene tradotto nel campo del file di configurazione metadata-cache:type-cache-max-size-mb.

    • Valori validi:

      • Valori di Quantità, ad esempio: 500Mi, 1Gi.
      • "-1": per consentire al tipo di cache di utilizzare la memoria necessaria.
      • "0": il tipo di cache è disabilitato.
      • Utilizza il valore predefinito 4Mi se il numero massimo di file all'interno di una singola directory del bucket che stai montando contiene 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, ovvero una media di circa 200 byte per file.

    • Valore predefinito: 4Mi.

  • metadataCacheTTLSeconds

    • Descrizione: la durata (TTL), in secondi, delle voci di metadati memorizzati nella cache. Se utilizzi 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. L'utilizzo del valore 0 genera una chiamata di metadati Get per garantire che la generazione dell'oggetto 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 utilizzi il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes, se utilizzi volumi temporanei 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. Per rendere visibili queste directory, puoi attivare il flag di montaggio implicit-dirs. Per scoprire di più, consulta la sezione File e directory nella documentazione GitHub di Cloud Storage FUSE.
  • Se utilizzi un contesto di sicurezza per il pod o container oppure se l'immagine container utilizza un utente o un gruppo non root, devi impostare i flag di montaggio uid e gid. Devi inoltre utilizzare i flag di montaggio file-mode e dir-mode per impostare le autorizzazioni del file system. Tieni presente che non puoi eseguire comandi chmod, chown o chgrp su un file system Cloud Storage FUSE, 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 di 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 farlo utilizzando il flag max-conns-per-host. Il numero massimo di connessioni TCP che definisci diventa effettivo quando --client-protocol viene 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 nel 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 i flag 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 consente di modificare il campo cache-dir nel file di configurazione di Cloud Storage FUSE, utilizzare l'attributo di 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.

Disabilita il driver CSI di Cloud Storage FUSE

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

Puoi disabilitare il driver CSI di Cloud Storage FUSE su 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 tuo cluster.

Risoluzione dei problemi

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

Passaggi successivi