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, accedi al bucket come se fosse una directory nel 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 le opzioni di montaggio per il volume.
Requisiti di memoria
I montaggi dei volumi 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 una durata (TTL) di 60 secondi per impostazione predefinita. La dimensione massima predefinita della cache stat è 32 MB, mentre la dimensione massima predefinita della cache dei tipi è 4 MiB.
Durante la lettura 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 consuma anche memoria diversa dalle cache stat e tipo, ad esempio un array da 1 MiB per ogni file che legge e per
goroutines.Quando scrive su Cloud Storage, Cloud Storage FUSE supporta
streaming-writes, un percorso di scrittura, per impostazione predefinita. Cloud Storage FUSE carica i dati direttamente su Cloud Storage senza eseguire la gestione temporanea completa del file. Ogni file aperto per le scritture in streaming consuma circa 64 MiB di memoria durante il processo di caricamento. In questo modo si riducono sia la latenza sia l'utilizzo dello spazio su disco, il che è particolarmente utile per le scritture sequenziali di grandi dimensioni.
Limitazioni
Poiché Cloud Run utilizza Cloud Storage FUSE per questo montaggio del volume, tieni presente alcuni aspetti quando monti un bucket Cloud Storage come volume:
- Cloud Storage FUSE non fornisce controllo della contemporaneità per più scritture (blocco dei file) sullo 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 avere un bucket Cloud Storage da montare come volume.
Per prestazioni di lettura/scrittura ottimali su Cloud Storage, consulta Ottimizza le 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:
- Cloud Run Developer (
roles/run.developer) sull'istanza Cloud Run - Utente dell'account di servizio (
roles/iam.serviceAccountUser) sull'identità di servizio
Per ottenere le autorizzazioni necessarie alla tua identità di servizio per accedere al file e al bucket Cloud Storage, chiedi all'amministratore di concedere all'identità di servizio il ruolo Storage Object Viewer (roles/storage.objectViewer). Se l'identità di servizio deve anche eseguire operazioni di scrittura in un bucket, concedi invece il ruolo Storage Object User (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, YAML o Terraform:
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:
trueper rendere il volume di sola lettura ofalseper consentire le scritture.
YAML
Se stai creando una nuova istanza, salta questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:
gcloud beta run instances describe INSTANCE --format export > instance.yaml
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 esempious-docker.pkg.dev/cloudrun/container/hello:latest.- VOLUME_NAME: un nome qualsiasi per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al montaggio del volume.
- MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio
/mnt/my-volume. - IS_READ_ONLY:
Trueper rendere il volume di sola lettura oFalseper consentire le scritture. - BUCKET_NAME: il nome del bucket Cloud Storage.
Crea o aggiorna l'istanza utilizzando il seguente comando:
gcloud beta run instances replace instance.yaml
Terraform
Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.
resource "google_cloud_run_v2_instance" "default" {
provider = google-beta
name = "INSTANCE"
location = "REGION"
launch_stage = "BETA"
containers {
image = "IMAGE_URL"
volume_mounts {
name = "VOLUME_NAME"
mount_path = "MOUNT_PATH"
}
}
volumes {
name = "VOLUME_NAME"
gcs {
bucket = google_storage_bucket.default.name
read_only = IS_READ_ONLY
}
}
}
resource "google_storage_bucket" "default" {
name = "BUCKET_NAME"
location = "REGION"
}
Sostituisci quanto segue:
- INSTANCE: il nome dell'istanza.
- REGION: la regione Google Cloud , ad esempio
us-west1. IMAGE_URL: un riferimento all'immagine container, ad esempious-docker.pkg.dev/cloudrun/container/hello:latest.- VOLUME_NAME: un nome qualsiasi per il 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:
trueper rendere il volume di sola lettura ofalseper consentire le scritture. - BUCKET_NAME: il nome del bucket Cloud Storage.
Lettura e scrittura su un volume
Se utilizzi la funzionalità di montaggio dei volumi 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.
Questo è particolarmente utile se utilizzi un container esistente che prevede che i dati vengano archiviati nel file system locale e utilizza le normali operazioni del file system per accedervi.
Gli snippet seguenti presuppongono un montaggio del volume con un mountPath impostato su /mnt/my-volume.
Nodejs
Utilizza il modulo File System per creare un nuovo file o aggiungerlo 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
Facoltativamente, puoi utilizzare le opzioni di montaggio per configurare varie proprietà del montaggio del volume. Le opzioni di montaggio disponibili consentono di configurare le impostazioni della cache, montare una directory specifica, attivare il logging di debug e altri comportamenti.
Specifica 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 virgola (;) 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) - Disattiva le directory implicite
- Specifica i livelli di logging di debug.
Configura le impostazioni di memorizzazione nella cache
Puoi modificare le impostazioni di memorizzazione nella cache per il volume impostando le opzioni di montaggio relative 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 Configura i montaggi dei volumi in memoria per i servizi. Quando attivi queste funzionalità, Cloud Run modifica la contabilità delle risorse del processo Cloud Storage FUSE e la conteggia ai fini dei limiti di memoria del container. Per aumentare il limite di memoria del container, consulta Configura i limiti di memoria per i servizi. |
|
file-cache-download-chunk-size-mb |
Specifica le dimensioni in MiB di ogni richiesta di lettura effettuata da ogni goroutine 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, con 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 della CPU sulla tua 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 di Cloud Storage FUSE quando la prima lettura viene completata da un offset diverso da zero. | false |
enable-buffered-read |
Abilita il buffering di lettura per precaricare i dati degli oggetti. Consigliato per i workload che leggono file di grandi dimensioni in sequenza (come modelli o set di dati di machine learning) per migliorare significativamente il throughput di lettura e ridurre la latenza di avvio dei container. | false |
stat-cache-max-size-mb |
Dimensione massima in mebibyte (MiB) che la cache delle statistiche può utilizzare. La cache delle statistiche viene sempre conservata 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 workload utilizza più di 20.000 file, aumenta la dimensione di valori di 10 per ogni 6000 file aggiuntivi, dove la cache delle statistiche utilizza in media 1500 byte per file.Per consentire alla cache delle statistiche di utilizzare la quantità di 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 può essere utilizzata dalla cache dei tipi. La cache dei tipi viene sempre conservata interamente in memoria, con un impatto 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 per ogni 5000 file, ovvero una media di circa 200 byte per file.Per consentire alla cache dei tipi di utilizzare la quantità di memoria necessaria, specifica un valore pari a -1.Per disabilitare la cache dei tipi, specifica un valore pari a 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 su 52 e 7 MiB:
Abilita il logging di debug
Per impostazione predefinita, Cloud Storage FUSE registra gli eventi con Info o un livello superiore. Puoi modificare le impostazioni di logging utilizzando uno dei seguenti livelli di gravità dei log, elencati in ordine crescente:
tracedebuginfowarningerror- Per disattivare tutti i log, 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 quando monta 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 file simulano 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 i costi dell'applicazione. Per saperne di più, consulta 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.
Monta 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, se il bucket contiene un numero elevato di file, il montaggio di una directory specifica può migliorare le prestazioni.
Puoi anche implementare questa soluzione per scopi di isolamento, se 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 UID e GID
Utilizza le opzioni di montaggio uid e gid per modificare l'identificatore dell'utente e l'identificatore gruppo per il volume. Questo è utile se vuoi impostare la proprietà del file su un utente o un gruppo specifico corrispondente 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: ID utente per montare il volume.
- GID: l'ID gruppo per montare il volume.
Imposta altre opzioni di montaggio
Di seguito è riportato l'elenco completo di tutte le opzioni di montaggio supportate da Cloud Run.
Directory
implicit-dirsonly-dirrename-dir-limit
Debug
debug_fuse_errorsdebug_fusedebug_gcsdebug-invariantsdebug_mutex
Cache
stat-cache-capacitystat-cache-ttltype-cache-ttlenable-nonexistent-type-cache
Autorizzazioni
uidgidfile-modedir-mode
Altro
billing-projectclient-protocolenable-buffered-readexperimental-enable-json-readexperimental-opentelemetry-collector-addresshttp-client-timeoutlimit-bytes-per-seclimit-ops-per-secmax-conns-per-hostmax-idle-conns-per-hostmax-retry-sleep-oretry-multipliersequential-read-size-mbstackdriver-export-interval
Per descrizioni dettagliate di queste opzioni, consulta Opzioni di montaggio della riga di comando di Cloud Storage FUSE. La pagina di Cloud Storage FUSE elenca tutte le opzioni FUSE disponibili, alcune delle quali non sono supportate da Cloud Run.
Ottimizza le prestazioni della larghezza di banda di rete di Cloud Storage FUSE
Per migliorare le prestazioni di lettura e scrittura, connetti la tua istanza Cloud Run a una rete VPC utilizzando il VPC diretto e instrada tutto il traffico in uscita attraverso la tua rete VPC. Puoi farlo utilizzando una delle seguenti opzioni:
- Abilita l'accesso privato Google, assicurandoti di impostare il parametro
vpc-egresssuall-traffic. - Utilizza una delle opzioni descritte nella pagina delle best practice di networking, nella sezione Traffico interno verso un'API di Google.
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 container. Di conseguenza, se il tentativo di connessione non va a buon fine, Cloud Storage FUSE non riuscirà a eseguire il montaggio e l'istanza Cloud Run non verrà avviata. Inoltre, se il montaggio di Cloud Storage FUSE richiede più di 30 secondi, 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, ciascuno che punta a un bucket diverso, verranno avviati due processi Cloud Storage FUSE. I montaggi e i processi avvengono 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 di Cloud Storage. Alcune operazioni, come l'elenco dei contenuti di un bucket, possono essere lente se la larghezza di banda della rete è bassa. Analogamente, la lettura di un file di grandi dimensioni può richiedere tempo, poiché anche questa operazione è limitata dalla larghezza di banda della rete.
Quando scrivi in un bucket, Cloud Storage FUSE esegue la gestione temporanea completa 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 trasferita 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:
- Documentazione di Cloud Storage FUSE
- Prestazioni di Cloud Storage FUSE
- Semantica di Cloud Storage FUSE
Cancella e rimuovi volumi e punti di montaggio dei volumi
Puoi cancellare tutti i volumi e i punti di montaggio oppure rimuovere singoli volumi e punti di montaggio.
Cancella tutti i volumi e i punti di montaggio dei volumi
Per cancellare tutti i volumi e i relativi montaggi dall'istanza con un singolo container, esegui questo comando:
gcloud beta run instances update INSTANCE \ --clear-volumes \ --clear-volume-mounts
Rimuovi singoli volumi e montaggi dei volumi
Per rimuovere un volume, devi anche rimuovere 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