Configura i montaggi dei volumi Cloud Storage per le istanze

Questa pagina mostra come montare un bucket Cloud Storage come volume di archiviazione, utilizzando i montaggi dei volumi di Cloud Run.

Il montaggio del bucket come volume in Cloud Run presenta i contenuti del bucket come file nel file system del container. Dopo aver montato il bucket come volume, puoi accedervi come se fosse una directory sul file system locale, utilizzando le operazioni e le librerie del file system del tuo linguaggio di programmazione anziché le librerie client delle API di Google.

Puoi montare il volume in sola lettura e specificare anche opzioni di montaggio per il volume.

Requisiti di memoria

I volumi di Cloud Storage utilizzano la memoria del container Cloud Run per le seguenti attività:

  • Per tutta la memorizzazione nella cache di Cloud Storage FUSE, Cloud Run utilizza l'impostazione della cache stat con un time-to-live (TTL) di 60 secondi per impostazione predefinita. La dimensione massima predefinita della cache delle statistiche è 32 MB, la dimensione massima predefinita della cache dei tipi è 4 MiB.

  • Quando legge da Cloud Storage, Cloud Storage FUSE effettua chiamate API per leggere un oggetto direttamente, senza scaricare l'intero file in una directory locale. Cloud Storage FUSE stabilisce una connessione TCP e legge l'intero oggetto Cloud Storage o solo le parti del file specificate nell'applicazione o nel sistema operativo tramite un offset. Durante la lettura, Cloud Storage FUSE utilizza anche la memoria diversa dalle cache di stat e di tipo, ad esempio un array di 1 MiB per ogni file letto e per goroutines.

  • Quando scrive in Cloud Storage, Cloud Storage FUSE supporta streaming-writes, un percorso di scrittura, per impostazione predefinita. Cloud Storage FUSE carica i dati direttamente in Cloud Storage senza eseguire completamente lo staging del file. Ogni file aperto per lo streaming scrive consuma circa 64 MiB di memoria durante il processo di caricamento. In questo modo si riducono sia la latenza che l'utilizzo dello spazio su disco, il che è particolarmente vantaggioso per le scritture sequenziali di grandi dimensioni.

Limitazioni

Poiché Cloud Run utilizza Cloud Storage FUSE per questo montaggio del volume, ci sono alcune cose da tenere a mente quando monti un bucket Cloud Storage come volume:

  • Cloud Storage FUSE non fornisce controllo della contemporaneità per più scritture (blocco file) nello stesso file. Quando più scritture tentano di sostituire un file, l'ultima scrittura ha la precedenza e tutte le scritture precedenti vengono perse.
  • Cloud Storage FUSE non è un file system completamente conforme a POSIX. Per maggiori dettagli, consulta la documentazione di Cloud Storage FUSE.

Percorsi non consentiti

Cloud Run non consente di montare un volume in /dev, /proc o /sys o nelle relative sottodirectory.

Prima di iniziare

Devi montare un bucket Cloud Storage come volume.

Per prestazioni di lettura/scrittura ottimali su Cloud Storage, consulta Ottimizzazione delle prestazioni della larghezza di banda di rete di Cloud Storage FUSE.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare i montaggi dei volumi Cloud Storage, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per ottenere le autorizzazioni necessarie all'identità di servizio per accedere al file e al bucket Cloud Storage, chiedi all'amministratore di concedere all'identità di servizio il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer). Se l'identità del servizio deve anche eseguire operazioni di scrittura in un bucket, concedi invece il ruolo Utente oggetti Storage (roles/storage.objectUser).

Per maggiori dettagli su ruoli e autorizzazioni di Cloud Storage, consulta IAM per Cloud Storage.

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se la tua istanza Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.

Monta un volume Cloud Storage

Puoi configurare un volume Cloud Storage per un'istanza Cloud Run utilizzando Google Cloud CLI o YAML:

gcloud

Per aggiungere un montaggio del volume:

gcloud beta run instances update INSTANCE \
--add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /mnt/my-volume.
  • BUCKET_NAME: il nome del bucket Cloud Storage.
  • READ_ONLY: true per rendere il volume di sola lettura o false per consentire le scritture.

YAML

  1. Se stai creando una nuova istanza, ignora questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml

  2. L'esempio seguente contiene la configurazione YAML:

    apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
  - image: IMAGE_URL
    volumeMounts:
    - name: VOLUME_NAME
      mountPath: MOUNT_PATH
  volumes:
  - name: VOLUME_NAME
    csi:
      driver: gcsfuse.run.googleapis.com
      readOnly: IS_READ_ONLY
      volumeAttributes:
        bucketName: BUCKET_NAME

    Sostituisci quanto segue:

    • INSTANCE: il nome dell'istanza Cloud Run.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
    • VOLUME_NAME: il nome che vuoi assegnare al volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
    • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /mnt/my-volume.
    • IS_READ_ONLY: True per rendere il volume di sola lettura oppure False per consentire le scritture.
    • BUCKET_NAME: il nome del bucket Cloud Storage.

  3. Crea o aggiorna l'istanza utilizzando il seguente comando:

    gcloud beta run instances replace instance.yaml

Lettura e scrittura in un volume

Se utilizzi la funzionalità di montaggio del volume di Cloud Run, accedi a un volume montato utilizzando le stesse librerie nel tuo linguaggio di programmazione che utilizzi per leggere e scrivere file nel file system locale.

Ciò è particolarmente utile se utilizzi un container esistente che prevede che i dati vengano archiviati nel file system locale e utilizza operazioni regolari del file system per accedervi.

I seguenti snippet presuppongono un montaggio del volume con mountPath impostato su /mnt/my-volume.

Nodejs

Utilizza il modulo File System per creare un nuovo file o aggiungere contenuti a un file esistente nel volume, /mnt/my-volume: 

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

Scrivi in un file conservato nel volume, /mnt/my-volume: 

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Vai

Utilizza il pacchetto os per creare un nuovo file conservato nel volume /mnt/my-volume: 

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Utilizza la classe Java.io.File per creare un file di log nel volume /mnt/my-volume: 

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

Configurazione del volume utilizzando le opzioni di montaggio

Se vuoi, puoi utilizzare le opzioni di montaggio per configurare varie proprietà del montaggio del volume. Le opzioni di montaggio disponibili ti consentono di configurare le impostazioni della cache, montare una directory specifica, attivare la registrazione di debug e altri comportamenti.

Specificare le opzioni di montaggio

Puoi specificare le opzioni di montaggio utilizzando Google Cloud CLI o YAML. Le opzioni di montaggio sono separate da punti e virgole (;) in Google Cloud CLI e da virgole in YAML, come mostrato nelle seguenti schede:

Opzioni di montaggio di uso comune

Le opzioni di montaggio vengono comunemente utilizzate per:

  • Configura impostazioni cache
  • Monta solo una directory specifica dal bucket Cloud Storage
  • Configura la proprietà del volume (uid, gid)
  • Disattivare le directory implicite
  • Specifica i livelli di logging di debug.

Configurare le impostazioni di memorizzazione nella cache

Puoi modificare le impostazioni di memorizzazione nella cache per il volume impostando le opzioni di montaggio correlate alla memorizzazione nella cache. La tabella seguente elenca le impostazioni, insieme ai valori predefiniti di Cloud Run:

Impostazione della cache Descrizione Predefinito
cache-dir Il nome del volume in memoria da utilizzare come directory sottostante per rendere persistenti i file del bucket Cloud Storage nel formato cr-volume:{volume name}. Ad esempio, se hai un volume in memoria denominato in-memory-1 che vuoi utilizzare come directory della cache, specifica cr-volume:in-memory-1. Per istruzioni sulla configurazione dei volumi in memoria, consulta Configurare i montaggi dei volumi in memoria per i servizi. Quando abiliti queste funzionalità, Cloud Run modifica la contabilizzazione delle risorse del processo Cloud Storage FUSE e la conteggia ai limiti di memoria del container. Per aumentare il limite di memoria del container, consulta Configurare i limiti di memoria per i servizi.
file-cache-download-chunk-size-mb Specifica le dimensioni di ogni richiesta di lettura in MiB che ogni goroutine invia a Cloud Storage durante il download dell'oggetto nella cache dei file. 200
file-cache-enable-parallel-downloads Accelera le letture di file di grandi dimensioni utilizzando la directory della cache dei file come buffer di precaricamento utilizzando più worker per scaricare più parti di un file in parallelo. true
file-cache-max-parallel-downloads Il numero massimo di goroutine che possono essere generate in un determinato momento in tutti i job di download dei file. Il doppio del numero di core CPU sulla macchina o 16, a seconda di quale sia il valore più alto.
file-cache-parallel-downloads-per-file Il numero di richieste di download simultanee per file. 16
file-cache-cache-file-for-range-read Determina se l'intero oggetto deve essere scaricato in modo asincrono e archiviato nella directory della cache FUSE di Cloud Storage al termine della prima lettura da un offset diverso da zero. false
stat-cache-max-size-mb Dimensione massima in mebibyte (MiB) che la cache delle statistiche può utilizzare. La cache delle statistiche viene sempre mantenuta interamente in memoria, il che influisce sul consumo di memoria. Specifica un valore di 32 se il tuo workload coinvolge fino a 20.000 file. Se il tuo carico di lavoro utilizza più di 20.000 file, aumenta le dimensioni di 10 per ogni 6000 file aggiuntivi, dove la cache delle statistiche utilizza una media di 1500 byte per file.

Per consentire alla cache delle statistiche di utilizzare tutta la memoria necessaria, specifica un valore di -1. Per disattivare la cache delle statistiche, specifica un valore di 0.		 32
type-cache-max-size-mb La dimensione massima in MiB per directory che la cache dei tipi può utilizzare. La cache dei tipi viene sempre mantenuta interamente in memoria, il che influisce sul consumo di memoria.

Specifica un valore di 4 se il numero massimo di file all'interno di una singola directory del bucket che stai montando contiene 20.000 file o meno. Se il numero massimo di file all'interno di una singola directory che stai montando contiene più di 20.000 file, aumenta il valore di 1 ogni 5000 file, ovvero una media di circa 200 byte per file.

Per consentire alla cache dei tipi di utilizzare tutta la memoria necessaria, specifica un valore di -1.

Per disattivare la cache dei tipi, specifica un valore di 0.		 4

Il seguente comando Google Cloud CLI imposta metadata-cache-ttl-secs su 120 secondi e aumenta la capacità della cache di statistiche e tipi rispettivamente a 52 e 7 MiB:

Attiva il logging di debug

Per impostazione predefinita, Cloud Storage FUSE registra gli eventi con Info o superiore. Puoi modificare le impostazioni di registrazione utilizzando uno dei seguenti livelli di gravità del log, elencati in ordine dal più basso al più alto:

  • trace
  • debug
  • info
  • warning
  • error
  • Per disattivare tutta la registrazione, specifica il valore off.

Quando specifichi un livello di gravità, Cloud Storage FUSE genera log per gli eventi con un livello di gravità uguale o superiore a quello specificato. Ad esempio, quando specifichi il livello warning, Cloud Storage FUSE genera log per avvisi ed errori.

L'impostazione della gravità dei log su livelli superiori a info può influire sulle prestazioni e generare una grande quantità di dati di logging, pertanto ti consigliamo di farlo solo se necessario. Per la compatibilità con Cloud Logging, il formato dei log è text e il formato json non è supportato.

La seguente riga di comando attiva il logging di debug:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug"

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /cache.
  • BUCKET_NAME: il nome del bucket Cloud Storage.

Disabilita directory implicite

Per far sembrare Cloud Storage più simile a un file system standard, Cloud Run abilita le directory implicite per impostazione predefinita durante il montaggio di un bucket Cloud Storage. Puoi disattivare le directory implicite utilizzando l'opzione di montaggio implicit-dirs. La disabilitazione delle directory implicite può migliorare le prestazioni e ridurre i costi, ma comporta compromessi in termini di compatibilità.

La funzionalità delle directory implicite consente a Cloud Run di riconoscere i file Cloud Storage preesistenti i cui nomi di file imitano una struttura di directory, ad esempio /mydir/myfile.txt. Se disattivi le directory implicite, Cloud Run non sarà in grado di elencare o leggere questi file.

La disattivazione delle directory implicite riduce il numero di richieste a Cloud Storage, il che potrebbe migliorare le prestazioni e il costo dell'applicazione. Per saperne di più, leggi la documentazione di Cloud Storage FUSE su file e directory.

La seguente riga di comando disattiva le directory implicite:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false"

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /cache.
  • BUCKET_NAME: il nome del bucket Cloud Storage.

Montare una directory specifica all'interno del bucket Cloud Storage

Per impostazione predefinita, Cloud Run monta l'intero bucket Cloud Storage, il che consente alle istanze Cloud Run di accedere a tutti i suoi contenuti. In alcuni casi potresti voler montare solo una directory specifica. Ad esempio, nel caso in cui il bucket contenga un numero elevato di file, il montaggio di una directory specifica può migliorare le prestazioni.

Puoi anche implementarlo per scopi di isolamento quando hai bisogno che istanze diverse abbiano accesso a directory diverse nel bucket di archiviazione.

La seguente riga di comando specifica la directory da montare:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images"

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /cache.
  • BUCKET_NAME: il nome del bucket Cloud Storage.

Imposta il volume su UID e GID

Utilizza le opzioni di montaggio uid e gid per modificare l'identificatore utente e l'identificatore gruppo per il volume. Questa operazione è utile se vuoi impostare la proprietà del file su un utente o un gruppo specifico che corrisponde all'identità di uno o più container in esecuzione. Per impostazione predefinita, i volumi sono di proprietà di root.

La seguente riga di comando imposta uid e gid:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /cache.
  • BUCKET_NAME: il nome del bucket Cloud Storage.
  • UID: l'ID utente per montare il volume.
  • GID: l'ID gruppo per montare il volume.

Impostare altre opzioni di montaggio

Di seguito è riportato l'elenco completo di tutte le opzioni di montaggio supportate da Cloud Run.

Directory

  • implicit-dirs
  • only-dir
  • rename-dir-limit

Debug

  • debug_fuse_errors
  • debug_fuse
  • debug_gcs
  • debug-invariants
  • debug_mutex

Cache

  • stat-cache-capacity
  • stat-cache-ttl
  • type-cache-ttl
  • enable-nonexistent-type-cache

Autorizzazioni

  • uid
  • gid
  • file-mode
  • dir-mode

Altro

  • billing-project
  • client-protocol
  • experimental-enable-json-read
  • experimental-opentelemetry-collector-address
  • http-client-timeout
  • limit-bytes-per-sec
  • limit-ops-per-sec
  • max-conns-per-host
  • max-idle-conns-per-host
  • max-retry-sleep
  • -o
  • retry-multiplier
  • sequential-read-size-mb
  • stackdriver-export-interval

Per descrizioni dettagliate di queste opzioni, consulta Opzioni di montaggio della riga di comando di Cloud Storage FUSE. La pagina Cloud Storage FUSE elenca tutte le opzioni FUSE disponibili, alcune delle quali non sono supportate da Cloud Run.

Ottimizzare le prestazioni della larghezza di banda di rete di Cloud Storage FUSE

Per migliorare le prestazioni di lettura e scrittura, connetti l'istanza Cloud Run a una rete VPC utilizzando il VPC diretto e instrada tutto il traffico in uscita attraverso la rete VPC. Puoi farlo utilizzando una delle seguenti opzioni:

Tempo di avvio del container e montaggi di Cloud Storage FUSE

L'utilizzo di Cloud Storage FUSE può aumentare leggermente il tempo di avvio a freddo del container Cloud Run perché Cloud Run avvia il montaggio del volume prima di avviare i container. Il container verrà avviato solo se Cloud Storage FUSE viene montato correttamente.

Tieni presente che Cloud Storage FUSE monta correttamente un volume solo dopo aver stabilito una connessione a Cloud Storage. Eventuali ritardi di rete possono influire sul tempo di avvio del contenitore. Di conseguenza, se il tentativo di connessione non va a buon fine, Cloud Storage FUSE non verrà montato e l'istanza Cloud Run non verrà avviata. Inoltre, se Cloud Storage FUSE impiega più di 30 secondi per il montaggio, l'istanza Cloud Run non verrà avviata perché Cloud Run ha un timeout totale di 30 secondi per eseguire tutti i montaggi.

Caratteristiche delle prestazioni di Cloud Storage FUSE

Se definisci due volumi, ognuno dei quali punta a un bucket diverso, verranno avviati due processi Cloud Storage FUSE. I montaggi e i processi vengono eseguiti in parallelo.

Le operazioni che utilizzano Cloud Storage FUSE sono influenzate dalla larghezza di banda della rete perché Cloud Storage FUSE comunica con Cloud Storage utilizzando l'API Storage. Alcune operazioni, come l'elenco dei contenuti di un bucket, possono essere lente se la larghezza di banda della rete è bassa. Allo stesso modo, la lettura di un file di grandi dimensioni può richiedere tempo, in quanto è limitata anche dalla larghezza di banda della rete.

Quando scrivi in un bucket, Cloud Storage FUSE esegue completamente lo staging dell'oggetto in memoria. Ciò significa che la scrittura di file di grandi dimensioni è limitata dalla quantità di memoria disponibile per l'istanza del container (il limite massimo di memoria del container è 32 GiB).

La scrittura viene scaricata nel bucket solo quando esegui un'operazione close o fsync: l'oggetto completo viene quindi caricato nel bucket. L'unica eccezione al caricamento completo di un oggetto nel bucket è il caso di un file con contenuti aggiunti quando il file è di almeno 2 MiB.

Per maggiori informazioni, consulta le seguenti risorse:

Cancella e rimuovi volumi e montaggi dei volumi

Puoi cancellare tutti i volumi e i montaggi oppure rimuovere singoli volumi e montaggi dei volumi.

Cancella tutti i volumi e i relativi punti di montaggio

Per cancellare tutti i volumi e i montaggi dei volumi dall'istanza a singolo container, esegui questo comando:

gcloud beta run instances update INSTANCE \
    --clear-volumes \
    --clear-volume-mounts

Rimuovere singoli volumi e montaggi dei volumi

Per rimuovere un volume, devi rimuovere anche tutti i montaggi dei volumi che lo utilizzano.

Per rimuovere singoli volumi o montaggi di volumi, utilizza i flag remove-volume e remove-volume-mount:

gcloud beta run instances update INSTANCE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH