Riferimento alla CLI Cloud Storage FUSE

L'interfaccia a riga di comando (CLI) di Cloud Storage FUSE, o CLI gcsfuse, consente di montare i bucket Cloud Storage come file system su una macchina locale. Questo documento descrive le opzioni del comando gcsfuse che puoi utilizzare per interagire con Cloud Storage FUSE.

Se utilizzi il driver CSI di Cloud Storage FUSE per montare i bucket sul file system locale in Google Kubernetes Engine, consulta Opzioni di montaggio per il driver CSI di Cloud Storage FUSE.

Struttura dei comandi dell'interfaccia a riga di comando gcsfuse

L'esempio seguente mostra la struttura del comando gcsfuse, inclusi i comandi obbligatori e le opzioni gcsfuse facoltative.

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Sostituisci quanto segue:

  • GLOBAL_OPTIONS sono le opzioni gcsfuse che controllano la configurazione del montaggio e il comportamento di Cloud Storage FUSE.

  • BUCKET_NAME è il nome del bucket da montare. Ad esempio, my-mount-bucket. Facoltativo. Escludi un nome di bucket da questo comando per eseguire il montaggio dinamico.

  • MOUNT_POINT è la directory locale in cui verrà montato il bucket. Ad esempio, /path/to/mount/point.

Opzioni dell'interfaccia a riga di comando gcsfuse

gcsfuse opzione Descrizione Valore valido Valore predefinito
Disabilita l'autenticazione per le richieste. Questa opzione deve essere impostata se utilizzi un endpoint personalizzato che non supporta l'autenticazione. Questa opzione deve essere impostata anche se utilizzi Cloud Storage FUSE con bucket pubblici. Valore booleano: true, false. false
Il nome dell'applicazione del mount. Valore stringa, ad esempio: my-bucket-mount. ""
Specifica un progetto da utilizzare per la fatturazione quando si accede al bucket montato. Questa opzione è spesso obbligatoria quando si monta un bucket abilitato per i pagamenti a carico del richiedente. Valore stringa che rappresenta un ID progetto. ""

Abilita la cache dei file e specifica la directory per l'archiviazione dei dati della cache dei file.

 Un percorso, ad esempio: /tmp/gcsfuse-cache-path. Un valore vuoto indica che questa opzione è disattivata. Questa opzione gcsfuse è disattivata per impostazione predefinita. ""
Specifica il protocollo utilizzato per comunicare con il backend Cloud Storage. http1

Esporta le metriche in Cloud Monitoring con l'intervallo specificato.

 Numero intero che rappresenta un valore in secondi, ad esempio: 10 (10 secondi). 0 specifica che non viene eseguita alcuna esportazione. 0
Specifica il percorso del file di configurazione che vuoi utilizzare per configurare i comportamenti di Cloud Storage FUSE. Un percorso, ad esempio: /etc/gcsfuse.yaml. ""
Specifica un endpoint personalizzato alternativo per il recupero dei dati. L'endpoint personalizzato deve supportare le risorse e le operazioni equivalenti all'endpoint gRPC di Cloud Storage, storage.googleapis.com:443, o all'endpoint JSON di Cloud Storage, https://storage.googleapis.com/storage/v1. Se non viene specificato un endpoint personalizzato, Cloud Storage FUSE utilizza l'endpoint JSON Cloud Storage globale. Se l'autenticazione non è supportata sull'endpoint personalizzato specificato, imposta l'opzione --anonymous-access gcsfuse su true per bypassare l'autenticazione. Un endpoint, ad esempio: storage.googleapis.com:443. ""
Abilita l'output di debug relativo a FUSE. Questa opzione è stata sostituita dall'opzione --log-severity gcsfuse. Per attivare l'output di debug, imposta l'opzione gcsfuse --log-severity su trace, che include i log di traccia, debug, informazioni, avviso ed errore. Valore booleano: true, false. false
Stampa le informazioni sulla richiesta e sulla tempistica di Cloud Storage. Questa opzione gcsfuse è stata sostituita dall'opzione --log-severity gcsfuse. Per attivare l'output di debug, imposta l'opzione gcsfuse --log-severity su trace, che include i log di traccia, debug, informazioni, avviso ed errore. Valore booleano: true, false. false
Esce dal programma quando vengono rilevate violazioni interne degli invarianti. Valore booleano: true, false. false
Stampa messaggi di debug quando un mutex viene mantenuto troppo a lungo. Se questa opzione gcsfuse è specificata, il livello di gravità dei log viene impostato automaticamente su trace, che include i log di traccia, debug, informazioni, avviso ed errore. Valore booleano: true, false. false
Bit di autorizzazione per le directory, in formato ottale. Valore stringa che rappresenta un numero intero ottale compreso tra "000" e "777" (inclusi), ad esempio: "755". 755
Specifica il precaricamento asincrono di parti di un oggetto Cloud Storage in un buffer in memoria, consentendo di eseguire le letture successive dal buffer anziché richiedere chiamate di rete. Valore booleano: true, false false
Crea una voce della cache dei tipi con il tipo NonexistentType se un file non viene trovato in Cloud Storage. Se il file viene creato in Cloud Storage, ma la voce NonexistentType per il file viene memorizzata nella cache, Cloud Storage FUSE non può richiedere il file finché la voce NonexistentType non viene rimossa dalla cache dei tipi. Valore booleano: true, false. false
Controlla il flusso del percorso di scrittura in modo che i dati vengano caricati direttamente su Cloud Storage man mano che vengono scritti, anziché eseguire la gestione temporanea completa della scrittura localmente e caricarli al momento di close() o fsync(). Per saperne di più sulle scritture in modalità flusso, consulta la sezione Semantica di Cloud Storage FUSE nella documentazione di GitHub di Cloud Storage FUSE. Valore booleano: true, false. true

Specifica la dimensione massima in MiB che la cache file può utilizzare e ti consente di limitare la capacità totale che la cache file può utilizzare all'interno della directory montata.
  • Numero intero
  • -1: specifica l'utilizzo dell'intera capacità disponibile della cache nella directory specificata per cache-dir. Questa è l'impostazione predefinita solo se viene passato cache-dir.
  • 0: disattiva la cache dei file.
 -1
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. Questa opzione gcsfuse deve essere impostata su true se prevedi di eseguire diverse letture casuali o parziali. Valore booleano: true, false. false
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. Numero intero 200

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.

I download paralleli vengono attivati automaticamente quando attivi la memorizzazione dei file nella cache. Per saperne di più sulla memorizzazione dei file nella cache, consulta Memorizzazione dei file nella cache in Cloud Storage FUSE.

Per scoprire di più sui download paralleli e su come configurare le proprietà di supporto, consulta Download paralleli.

 Valore booleano: true, false. true
Un'espressione regolare che specifica i file da escludere dalla memorizzazione nella cache. Se un file corrisponde a questa espressione regolare, non viene memorizzato nella cache, anche se corrisponde anche a --file-cache-include-regex. L'espressione regolare viene confrontata con i percorsi dei file nel formato bucket_name/object_key. Per saperne di più, consulta Controlla la memorizzazione nella cache a livello di granularità dei file utilizzando le espressioni regolari. Valore stringa che rappresenta un'espressione regolare. ""
Un'espressione regolare che specifica i file da includere nella memorizzazione nella cache. Se questa opzione viene utilizzata, vengono memorizzati nella cache solo i file corrispondenti a questa espressione regolare. L'espressione regolare viene confrontata con i percorsi dei file nel formato bucket_name/object_key. Per saperne di più, consulta Controlla la memorizzazione nella cache a livello di granularità dei file utilizzando le espressioni regolari. Valore stringa che rappresenta un'espressione regolare. ""
Il numero massimo di goroutine che possono essere generate in un determinato momento in tutti i job di download dei file.
  • Numero intero
  • -1: specifica download paralleli illimitati.
  • 0: disattiva i download paralleli. Può essere utilizzato solo se --enable-parallel-downloads non viene passato o viene passato come false.
 Il doppio del numero di core della CPU sulla tua macchina o 16, a seconda di quale sia il valore più alto.
Il numero di richieste di download simultanee per file. Numero intero 16
Specifica i bit di autorizzazione per i file, in formato ottale. Valore stringa che rappresenta un numero intero ottale compreso tra "000" e "777" (inclusi), ad esempio: "644". 644
Esegue il comando gcsfuse in primo piano. Valore booleano: true, false. false
Specifica il proprietario dell'ID gruppo (GID) di tutti gli inode.
  • Numero intero che rappresenta un GID.
  • -1: viene utilizzato il GID del chiamante.
 -1
Visualizza la guida su Cloud Storage FUSE. Nessuno Nessuno
Mostra la versione di Cloud Storage FUSE installata. Nessuno Nessuno
Specifica per quanto tempo il client HTTP di Cloud Storage FUSE può attendere per ricevere una risposta dal server prima del timeout. Durata, ad esempio: 1h10m10s per 1 ora, 10 minuti e 10 secondi. 0s specifica che non è previsto alcun timeout. 0s
Indica a Cloud Storage FUSE di ignorare i segnali di interruzione del sistema, come SIGINT attivato da Control+C. In questo modo, i segnali non interrompono le operazioni in corso. Valore booleano: true, false. true
Include implicitamente cartelle e cartelle gestite. Per saperne di più, consulta File e directory nella documentazione di GitHub su Cloud Storage FUSE. Valore booleano: true, false. false

Attiva la cache degli elenchi e definisce la durata (TTL) in secondi delle voci memorizzate nella cache. La cache dell'elenco viene conservata in memoria nella cache della pagina, che è controllata dal kernel in base alla memoria disponibile.
  • Numero intero che rappresenta i secondi, ad esempio: 10 (10 secondi).
  • 0: disattiva la memorizzazione nella cache degli elenchi.
  • -1: ignora la scadenza della voce e restituisce sempre la risposta dell'elenco dalla cache, se disponibile.
 0
Specifica un percorso assoluto del file della chiave JSON delle credenziali per l'autenticazione delle richieste a Cloud Storage. Per impostazione predefinita, Cloud Storage FUSE utilizza le Credenziali predefinite dell'applicazione per autenticare le richieste. Un percorso, ad esempio: /home/example_user/gcloud-key.json. Se questa opzione non è impostata, vengono utilizzate le credenziali predefinite dell'applicazione.
Specifica il limite di larghezza di banda con cui Cloud Storage FUSE può leggere i dati da Cloud Storage, misurato in un intervallo di 30 secondi. Numero in virgola mobile. -1 non specifica alcun limite. -1
Specifica un limite per le operazioni eseguite al secondo, misurate in un intervallo di 30 secondi. Numero in virgola mobile. -1 non specifica alcun limite. -1
Specifica il file per l'archiviazione dei log che possono essere analizzati da Fluentd. Un percorso, ad esempio: /tmp/user-example-bucket-gcsfuse-logs.txt. stdout quando Cloud Storage FUSE viene eseguito in primo piano o syslog quando Cloud Storage FUSE viene eseguito in background
Specifica il formato del file di log.
  • text
  • json
 json
Il numero massimo di file di log ruotati da conservare, escluso il file attivo in cui vengono scritti i log.
  • Numero intero
  • 0: conserva tutti i file di log ruotati
 10
Specifica se i file di log ruotati vengono compressi utilizzando gzip. Valore booleano: true, false. true
La dimensione massima in megabyte (MB) che i file di log possono raggiungere prima di essere ruotati. Numero intero. Il valore minimo è 1. 512

Il livello di gravità per cui vuoi che Cloud Storage FUSE generi i log. I livelli di gravità sono ordinati dal più basso al più alto. Ad esempio, quando specifichi warning, Cloud Storage FUSE genera log per avvisi ed errori. In genere, consigliamo di utilizzare il livello di gravità info.
  • off: disattiva tutti i log.
  • error: contiene messaggi relativi a problemi gravi che impediscono a Cloud Storage FUSE di completare un'operazione o indicano un errore, ad esempio errori di montaggio, errori di autorizzazione ed errori critici di input/output (I/O).
  • warning: contiene messaggi che indicano potenziali problemi che non sono critici, ma che possono causare problemi se non vengono risolti. I potenziali problemi includono problemi di connessione non irreversibili, avvisi di ritiro, conflitti di risorse che potrebbero causare un leggero peggioramento delle prestazioni e nuovi tentativi per errori temporanei. Questo livello di gravità include anche le informazioni fornite nel livello di gravità error.
  • info: contiene informazioni generali di logging, come i messaggi di avvio e arresto o informazioni sulle operazioni di montaggio riuscite, sugli aggiornamenti di avanzamento e sulle impostazioni di configurazione. Questo livello di gravità include anche informazioni sui livelli di gravità warning e error.
  • debug: contiene informazioni di logging come messaggi di avvio e arresto o informazioni su operazioni di montaggio riuscite, aggiornamenti sull'avanzamento e impostazioni di configurazione. Questo livello di gravità include anche le informazioni fornite nei livelli di gravità info, warning e error.
  • trace: contiene dettagli granulari su ogni operazione e chiamata di funzione di Cloud Storage FUSE, delineando l'interazione di gcsfuse con il driver FUSE del kernel e Cloud Storage. Questo livello di gravità include anche i dettagli forniti nei livelli di gravità debug, info, warning e error.
 info
Specifica il numero massimo di connessioni TCP consentite per server. Questo criterio diventa effettivo quando --client-protocol è impostato su http1. Numero intero compreso tra 0 e 2147483647. 0 non specifica alcun limite per le connessioni TCP. 0
Specifica il numero massimo di connessioni inattive consentite per server. Questo criterio diventa effettivo quando --client-protocol è impostato su http1. Numero intero compreso tra 0 e 2147483647. 0 non specifica alcun limite per le connessioni inattive. 0
Specifica il numero massimo di volte in cui un'operazione viene ripetuta se non va a buon fine, evitando loop di tentativi ripetuti all'infinito.
  • Numero intero che rappresenta il numero massimo di nuovi tentativi, ad esempio: 10.
  • 0: consente un numero illimitato di tentativi di ripetizione.
 0
Specifica la durata massima per cui Cloud Storage FUSE può rimanere in stato di sospensione in un ciclo di nuovi tentativi con backoff esponenziale. Una volta che la durata del backoff supera la durata massima specificata, il nuovo tentativo continua con la durata massima specificata. Durata, ad esempio: 1h5m50s (1 ora, 5 minuti e 50 secondi) o 60s (60 secondi). 30s

Definisce la durata (TTL) in secondi delle voci della cache delle statistiche negative, che memorizzano i risultati per i file inesistenti nella cache.
  • Numero intero che rappresenta i secondi, ad esempio: 10 (10 secondi).
  • 0: disabilita la memorizzazione nella cache negativa delle statistiche.
  • -1: consente la memorizzazione nella cache delle statistiche negative senza limiti e disabilita la scadenza del TTL.
 5
Definisce la durata (TTL) in secondi delle voci dei metadati memorizzate nella cache.
  • Numero intero che rappresenta i secondi, ad esempio: 30 (30 secondi).
  • -1: ignora la scadenza del TTL e pubblica i file dalla cache ogni volta che sono disponibili.
  • 0: utilizza il file più aggiornato. L'utilizzo di questo valore genera una chiamata ai metadati Get per assicurarsi che la generazione dell'oggetto per il file nella cache corrisponda a quella archiviata in Cloud Storage.
 60
Specifica opzioni di montaggio aggiuntive specifiche del sistema. La maggior parte delle opzioni di montaggio generiche in FUSE, come suid, è supportata da Cloud Storage FUSE e può essere passata insieme all'opzione -o. Opzioni di montaggio in FUSE, ad esempio:
  • rw: monta in modalità di lettura e scrittura.
  • ro: monta in modalità di sola lettura.
 ""
Monta solo una directory specifica all'interno di un bucket. Un percorso, ad esempio: /etc/gcsfuse.yaml. ""
Applica un insieme predefinito e ottimizzato di configurazioni di Cloud Storage FUSE per la memorizzazione nella cache, il threading e le dimensioni del buffer per aiutarti a ottenere prestazioni elevate per un tipo di workload specifico, come l'addestramento, la distribuzione e il checkpointing. Per saperne di più su ogni configurazione predefinita in base al tipo di workload, consulta Configurazioni basate su profili per i workload AI/ML.
  • Una stringa, ad esempio "aiml-checkpointing".
  • "aiml-training": ottimizza le prestazioni per letture con throughput elevato di set di dati di grandi dimensioni e impedisce all'hardware Cloud GPU e Cloud TPU di attendere i dati.
  • aiml-checkpointing: ottimizza le prestazioni per le scritture con throughput elevato per file di grandi dimensioni riducendo drasticamente il tempo necessario per salvare i checkpoint di più gigabyte, riducendo al minimo le pause di addestramento.
  • aiml-serving: ottimizza le prestazioni per i workload di distribuzione semplificando l'accesso ai dati e applicando meccanismi di memorizzazione nella cache.
 ""

Espone l'endpoint delle metriche di Prometheus sulla porta specificata e sul percorso /metrics.

 Numero intero che rappresenta la porta che vuoi specificare. 0

Specifica il numero massimo di blocchi disponibili per le letture con buffer in tutti gli handle di file.
  • Numero intero
  • 0: disattiva le letture con buffer.
  • -1: imposta il valore su blocchi illimitati.
 40
Consente di rinominare le directory contenenti un numero di discendenti inferiore al limite specificato. Numero intero compreso tra 0 e 2147483647. 0
Specifica il moltiplicatore per il backoff esponenziale tra tentativi consecutivi. Numero in virgola mobile. 2
Specifica se riutilizzare il token acquisito da --token-url. Valore booleano: true, false. true
Specifica le dimensioni dei blocchi di dati da scaricare da Cloud Storage, in megabyte (MB). Numero intero compreso tra 1 e 1024. 200
Specifica il numero di voci che la cache stat può contenere. Questa opzione gcsfuse è stata sostituita dall'opzione --stat-cache-max-size-mb gcsfuse. Numero intero 4096
La dimensione massima della memoria che la cache stat può utilizzare, in MiB. La cache delle statistiche viene sempre conservata interamente in memoria.
  • Numero intero. I nostri consigli:
    • 34 se il tuo workload coinvolge fino a 20.000 file.
    • Se il tuo workload è superiore a 20.000 file, aumenta le dimensioni di 10 per ogni 6000 file aggiuntivi, dove la cache stat utilizza una media di 1720 byte per file (inclusi 220 per le informazioni sul tipo).
  • -1: non imposta alcun limite, per cui la cache delle statistiche utilizza tutta la memoria necessaria.
  • 0: disattiva la cache delle statistiche.
 34
Specifica per quanto tempo memorizzare nella cache i risultati di StatObject e gli attributi inode. Questa opzione è stata sostituita dall'opzione --metadata-cache-ttl-secs gcsfuse. Durata, ad esempio: 20s (20 secondi). 60s
Specifica un percorso alla directory temporanea in cui vengono eseguite le fasi di scrittura prima del caricamento su Cloud Storage. Un percorso, ad esempio: /mnt/ssd/example-user-gcsfuse-temp-dir. /tmp
Specifica un URL per ottenere un token di accesso quando --key-file non è presente. Un URL. ""
Specifica per quanto tempo memorizzare nella cache la mappatura tra nomi e file o directory negli inode della directory, in secondi. Questa opzione gcsfuse è stata sostituita dall'opzione --metadata-cache-ttl-secs gcsfuse. Durata in secondi, ad esempio: 20s (20 secondi). 60s
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.
  • Numero intero. I nostri consigli:
    • 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.
  • -1: non specifica alcun limite e consente alla cache dei tipi di utilizzare tutta la memoria necessaria.
  • 0: disattiva la cache dei tipi.
 4
Abilita il precaricamento in background dei metadati per gli oggetti all'interno di una directory durante un fallimento della cache. Questo flag esegue un aggiornamento batch della cache dei metadati, riducendo in modo significativo la latenza per le ricerche successive dei file nella directory. Valore booleano: true, false. false
Specifica il numero massimo di voci di metadati da precaricare per directory. I valori che specificano più di 5000 voci di metadati generano più chiamate Cloud Storage Objects: list sequenziali, poiché ogni singola chiamata è limitata a 5000 risultati. Numero intero compreso tra -1 e 2147483647. Imposta su -1 per precaricare tutte le voci. 5000
Il numero massimo di worker in background simultanei autorizzati a eseguire il precaricamento dei metadati in tutte le directory. Numero intero compreso tra -1 e 2147483647. Imposta su -1 per un numero illimitato di worker. 10
Specifica l'identificatore dell'utente (UID) proprietario di tutti gli inode.
  • Numero intero che rappresenta un UID.
  • -1: viene utilizzato l'UID del chiamante.
 -1

Specifica il numero massimo di blocchi di dati disponibili per le scritture in streaming su tutti i file. Per impostazione predefinita, ogni file utilizza un chunk di dati da 32 MiB.
  • Numero intero
  • 0: disattiva le scritture in modalità flusso di dati.
  • -1: imposta il valore su un numero illimitato di chunk.
  • Valore predefinito per le macchine con specifiche basse e risorse limitate: 4
  • Valore predefinito per le macchine con specifiche elevate e una grande quantità di risorse: 1600

Torna all'inizio