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 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 operazioni comuni di I/O su file (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 come volumi i bucket Cloud Storage preesistenti. Le 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 di 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 memorizzazione nella cache dei file per migliorare le prestazioni di lettura delle applicazioni che gestiscono piccoli file dai bucket Cloud Storage. La funzionalità Cache file di Cloud Storage FUSE è una cache di lettura basata su client che consente di fornire più rapidamente letture ripetute dei file dall'archiviazione cache di tua scelta. Puoi scegliere tra un'ampia gamma 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 rapporto prezzo/prestazioni. Devi 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 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 Autopilot.
  • Il driver CSI di Cloud Storage FUSE non richiede l'accesso con privilegi normalmente richiesto dai client FUSE. Ciò consente una migliore strategia di sicurezza.
  • Il supporto di 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 Workload Identity Federation per GKE per gestire l'autenticazione e avere un controllo granulare sul modo in cui i pod accedono agli oggetti Cloud Storage.
  • Se esegui l'addestramento e la gestione dei carichi di lavoro ML con framework come Ray, PyTorch, Spark e TensorFlow, la portabilità e la semplicità fornite dal driver CSI di Cloud Storage FUSE ti consentono di eseguire i tuoi carichi di lavoro direttamente sui tuoi cluster GKE senza ulteriori modifiche al codice.
  • Puoi leggere gli oggetti Cloud Storage in cui è abilitata la memorizzazione nella cache dei file per migliorare le prestazioni di lettura. Per saperne di più sui vantaggi della memorizzazione nella cache di file, consulta la documentazione di Cloud Storage FUSE.
  • Puoi consumare i volumi Cloud Storage FUSE nei 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 initialize gcloud CLI. Se hai già installato gcloud CLI, scarica 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 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 di 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 di GKE per GKE

Per rendere i bucket Cloud Storage accessibili dal tuo cluster GKE utilizzando la federazione di Workload Identity per GKE, segui questi passaggi. Per ulteriori informazioni, consulta Configurare le applicazioni per l'utilizzo della federazione di Workload Identity 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 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 ServiceAccount Kubernetes.

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

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Sostituisci quanto segue:

    • KSA_NAME: il nome del tuo nuovo ServiceAccount Kubernetes.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per l'Account ServiceAccount Kubernetes.

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

    Puoi concedere il ruolo al tuo ServiceAccount 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: nome del bucket Cloud Storage.
    • PROJECT_NUMBER: il numero di progetto numerico 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 ServiceAccount Kubernetes.
    • KSA_NAME: il nome del tuo nuovo ServiceAccount 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 e scrittura, utilizza il ruolo Utente oggetti Storage (roles/storage.objectUser).

    Se vuoi, puoi concedere il ruolo al tuo ServiceAccount Kubernetes per accedere a tutti i bucket Cloud Storage nel 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 bucket Cloud Storage.
    • PROJECT_NUMBER: il numero di progetto numerico 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 ServiceAccount Kubernetes.
    • KSA_NAME: il nome del tuo nuovo ServiceAccount 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 e scrittura, utilizza il ruolo Utente oggetti Storage (roles/storage.objectUser).

Preparati a montare i bucket Cloud Storage FUSE

Questa sezione illustra come prepararti a montare i bucket Cloud Storage FUSE sui tuoi cluster.

Specifica le annotazioni dei pod

Il driver CSI si basa sulle annotazioni dei pod per identificare se il pod utilizza volumi supportati da Cloud Storage. Se il driver rileva le annotazioni necessarie, inserisce un container collaterale chiamato gke-gcsfuse-sidecar nel pod dei carichi 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 abilitare il driver CSI a 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

Quando decidi la quantità di risorse da allocare, tieni presente quanto segue:

  • Se imposti solo una delle annotazioni relative alle richieste di risorse o ai limiti, GKE applica gli stessi valori per le richieste di risorse e il limite di risorse.
  • Se il pod del carico di lavoro utilizza più volumi di Cloud Storage, le risorse del container collaterali 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.
  • Alloca più CPU al container collaterale se i tuoi carichi di lavoro richiedono una velocità effettiva superiore. CPU insufficiente causerà una 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 della memoria di Cloud Storage FUSE per la memorizzazione nella cache dei metadati è proporzionale al numero di file, ma non alla loro dimensione. Una memoria insufficiente causerà errori di esaurimento della memoria di Cloud Storage FUSE e arresterà l'applicazione del carico di lavoro.
  • Per la memorizzazione nella cache di file, Cloud Storage FUSE per impostazione predefinita memorizza nella cache i file in una directory temporanea locale. Stima la quantità di spazio libero necessario al tuo carico di lavoro per la memorizzazione nella cache dei file e aumenta il limite di archiviazione temporaneo. Per scoprire di più, consulta la sezione sugli attributi relativi al volume.
  • Per le operazioni di scrittura, Cloud Storage FUSE per impostazione predefinita archivia i file in una directory temporanea locale prima che vengano caricati nel bucket Cloud Storage. Stima lo spazio libero necessario al tuo carico di lavoro per la gestione temporanea durante la scrittura di file di grandi dimensioni e aumenta di conseguenza il limite di spazio di archiviazione temporaneo. Per scoprire 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 eventuali limiti delle 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. Questo è utile quando non puoi decidere la quantità di risorse necessarie a Cloud Storage FUSE per i tuoi carichi di lavoro e vuoi consentire a Cloud Storage FUSE di consumare 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 container collaterale

Questa sezione descrive come utilizzare l'immagine container collaterale se la stai ospitando 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 collaterale privata, 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 il solo campo image. GKE utilizzerà l'immagine del container collaterale specificata per prepararsi all'iniezione 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 tag immagine del container collaterale privato.

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

Questa sezione descrive come configurare un volume del 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 inserire temporaneamente i file nelle operazioni di scrittura. Puoi specificare qualsiasi tipo 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. Nell'esempio seguente viene illustrato 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 per l'oggetto PVC.

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

Questa sezione descrive come configurare un volume personalizzato della cache 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 i file nella cache nelle operazioni di lettura. Puoi specificare qualsiasi tipo 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 di dimensioni superiori a 10 GiB nei cluster Autopilot. Per utilizzare il volume personalizzato della cache, devi specificare un valore fsGroup diverso da zero. Nell'esempio seguente viene illustrato 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 per l'oggetto PVC.

Esegui il provisioning del 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 dei pod.

Utilizza 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 campi seguenti:

    • metadata.annotations: l'annotazione gke-gcsfuse/volumes: "true" è obbligatoria. Consulta Configurare 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 eliminare i dati dopo l'uscita dall'applicazione. Per saperne di più, consulta Best practice per Kubernetes: terminazione con periodo di tolleranza.
    • spec.serviceAccountName: utilizza lo stesso ServiceAccount Kubernetes del passaggio Configura 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 i bucket a cui può accedere Kubernetes ServiceAccount. Per ulteriori informazioni, 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 con una sola stringa separati da virgole, senza spazi.
    • spec.volumes[n].csi.volumeAttributes: facoltativo. Passa altri attributi del volume a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: facoltativo. Specifica true se tutti i montaggi dei volumi 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 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 uscirà automaticamente dopo l'uscita di tutti gli altri container del carico di lavoro.

Per ulteriori esempi, consulta 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
  claimRef:
    namespace: NAMESPACE
    name: gcs-fuse-csi-static-pvc
  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 campi seguenti:

    • spec.claimRef.namespace: specifica lo spazio dei nomi PersistentVolumeClaim.
    • spec.claimRef.name: specifica il nome dell'oggetto PersistentVolumeClaim.
    • 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 ha accesso l'account di servizio Kubernetes configurato. Per saperne di più, consulta la sezione 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 PersistentVolumeClaim per associare l'PersistentVolume. L'esempio include i campi seguenti:

    • 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, assicurati di seguire queste linee guida:

    • I campi di spec.storageClassName nei file manifest PV e PVC devono corrispondere. storageClassName non deve fare riferimento a un oggetto StorageClass esistente. Per associare la richiesta a un volume, puoi utilizzare il nome che preferisci, ma non può essere vuoto.
    • I campi di spec.accessModes nei file 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 qualsiasi numero 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 ulteriori esempi, consulta Applicazioni di esempio nella documentazione del progetto GitHub.

Utilizza 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 abilitare e controllare la memorizzazione nella cache dei file, utilizza l'attributo del volume fileCacheCapacity.

GKE utilizza un volume emptyDir per la memorizzazione nella cache del file di Cloud Storage FUSE supportata dal disco di avvio della VM del nodo. Se abiliti l'SSD locale sul nodo, GKE utilizza l'SSD locale per supportare il 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 CPU e GPU GPU con supporto SSD locale, consigliamo di utilizzare l'archiviazione SSD locale. Per le famiglie TPU o Autopilot, consigliamo di utilizzare Disco permanente bilanciato o Disco permanente SSD.

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 Cloud Storage FUSE tramite un volume temporaneo CSI con memorizzazione nella cache di 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 inizializzazione data-loader genera 1000 file con una dimensione di 64 kB e li carica in un bucket Cloud Storage. Il container principale data-validator legge tutti i file del 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 di 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 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 cache locale è molto più veloce della prima lettura 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 nel file system locale. Per l'elenco completo delle opzioni di montaggio supportate, consulta la documentazione relativa all'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 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 deve essere generata da 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 di volume viene convertito nel campo del file di configurazione logging:severity.

    • Valori validi (in ordine di gravità più basso):

      • 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 di volume viene convertito nel campo del file di configurazione file-cache:max-size-mb.

    • Valori validi:

      • Valori della 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 la prima lettura viene eseguita da un offset diverso da zero. Deve essere impostato su "true" se prevedi di eseguire diverse letture casuali o parziali. Questo attributo di 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: le dimensioni massime utilizzabili nella cache delle statistiche. 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 verrà tradotto correttamente in questa nuova configurazione. Questo attributo di volume viene convertito nel campo del file di configurazione metadata-cache:stat-cache-max-size-mb.

    • Valori validi:

      • Valori della 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 di 32Mi se il carico di lavoro riguarda fino a 20.000 file. Se il carico di lavoro ha dimensioni superiori a 20.000 file, aumenta le dimensioni in base a valori di 10 MiB per ogni 6000 file aggiuntivi, ovvero una media di circa 1500 byte per file.

    • Valore predefinito: 32Mi.

  • metadataTypeCacheCapacity

    • Descrizione: la dimensione massima per directory utilizzabile dalla cache dei tipi. La cache dei tipi viene sempre mantenuta interamente in memoria. Questo attributo di volume viene convertito nel campo del file di configurazione metadata-cache:type-cache-max-size-mb.

    • Valori validi:

      • Valori della quantità, ad esempio: 500Mi, 1Gi.
      • "-1": per consentire alla cache del tipo di utilizzare la quantità di memoria necessaria.
      • "0": la cache dei tipi è disattivata.
      • Utilizza il valore predefinito 4Mi se il numero massimo di file in una singola directory dal bucket che stai montando contiene 20.000 file o meno. Se il numero massimo di file in una singola directory che stai montando contiene più di 20.000 file, aumenta le dimensioni 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 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 verranno tradotti correttamente in questa nuova configurazione. Questo attributo di volume viene convertito 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 elabora il file dalla cache ogni volta che è disponibile.
      • "0": assicurati che venga letto il file più aggiornato. L'utilizzo di un valore 0 genera una chiamata di metadati Get per assicurare 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 utilizzi il provisioning statico.
  • Nel campo spec.volumes[n].csi.volumeAttributes, se utilizzi volumi temporanei CSI.

Considerazioni

Quando configuri i montaggi, tieni presente quanto segue:

  • 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 File e directory nella documentazione GitHub di Cloud Storage FUSE.
  • Se utilizzi un contesto di sicurezza per il pod o il container oppure se l'immagine container utilizza un gruppo o un utente non root, devi impostare i flag di montaggio uid e gid. Devi utilizzare anche 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 file system di Cloud Storage FUSE, di conseguenza 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 solo montare 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 di Cloud Storage FUSE.
  • Se il numero di core o thread è superiore a 100, imposta max-conns-per-host su questo valore.
  • 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 codici 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 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; utilizza l'attributo di volume fileCacheCapacity per abilitare o disabilitare la memorizzazione nella cache del file. Per sostituire il volume emptyDir predefinito per la memorizzazione nella cache dei file, puoi configurare un volume di 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 cluster.

Risoluzione dei problemi

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

Passaggi successivi