File di configurazione Cloud Storage FUSE

Un file di configurazione di Cloud Storage FUSE ti consente di definire in modo permanente il comportamento di Cloud Storage FUSE in un file YAML anziché specificare le opzioni ogni volta che monti un bucket. Per utilizzare il file di configurazione, specifica il percorso nell'opzione --config-file quando esegui il comando gcsfuse.

Questo documento descrive il formato del file di configurazione e i campi supportati. Puoi anche controllare lo stesso comportamento utilizzando l'interfaccia a riga di comando di Cloud Storage FUSE.

Formato e campi del file di configurazione di Cloud Storage FUSE

L'esempio di configurazione YAML seguente mostra il formato e i campi disponibili in Cloud Storage FUSE.

app-name: "APP_NAME"
logging:
  file-path: "FILE_PATH"
  format: FORMAT
  severity: SEVERITY
  log-rotate:
    max-file-size-mb: MAX_FILE_SIZE
    backup-file-count: BACKUP_FILE_COUNT
    compress: COMPRESS
cache-dir: "CACHE_DIR"
file-cache:
  max-size-mb: MAX_SIZE
  cache-file-for-range-read: CACHE_FILE_FOR_RANGE_READ
  enable-parallel-downloads: ENABLE_PARALLEL_DOWNLOADS
  exclude-regex: EXCLUDE_REGEX
  include-regex: INCLUDE_REGEX
  parallel-downloads-per-file: PARALLEL_DOWNLOADS_PER_FILE
  max-parallel-downloads: MAX_PARALLEL_DOWNLOADS
  download-chunk-size-mb: DOWNLOAD_CHUNK_SIZE
metadata-cache:
  negative-ttl-secs: ENABLE_NEGATIVE_TTL_SECS
  stat-cache-max-size-mb: STAT_CACHE_MAX_SIZE
  ttl-secs: TTL_SECS
  enable-metadata-prefetch: ENABLE_METADATA_PREFETCH
  metadata-prefetch-entries-limit: METADATA_PREFETCH_ENTRIES_LIMIT
  metadata-prefetch-max-workers: METADATA_PREFETCH_MAX_WORKERS
only-dir: "ONLY_DIR"
gcs-auth:
  anonymous-access: ANONYMOUS_ACCESS
  key-file: "KEY_FILE"
  reuse-token-from-url: REUSE_TOKEN_FROM_URL
  token-url: "TOKEN_URL"
gcs-connection:
  billing-project: "BILLING_PROJECT"
  client-protocol: CLIENT_PROTOCOL
  custom-endpoint: "CUSTOM_ENDPOINT"
  http-client-timeout: HTTP_CLIENT_TIMEOUT
  limit-bytes-per-sec: "LIMIT_BYTES_PER_SEC"
  limit-ops-per-sec: "LIMIT_OPS_PER_SEC"
  max-conns-per-host: MAX_CONNS_PER_HOST
  max-idle-conns-per-host: MAX_IDLE_CONNS_PER_HOST
  sequential-read-size-mb: SEQUENTIAL_READ_SIZE
implicit-dirs: IMPLICIT_DIRS
file-system:
  kernel-list-cache-ttl-secs: KERNEL_LIST_CACHE_TTL_SECS
  ignore-interrupts: IGNORE_INTERRUPTS
  dir-mode: "DIR_MODE"
  file-mode: "FILE_MODE"
  fuse-options: FUSE_OPTIONS
  gid: GID
  rename-dir-limit: RENAME_DIR_LIMIT
  temp-dir: "TEMP_DIR"
  uid: UID
foreground: FOREGROUND
gcs-retries:
  max-retry-attempts: MAX_RETRY_ATTEMPTS
  max-retry-sleep: MAX_RETRY_SLEEP
  multiplier: "MULTIPLIER"
metrics:
  cloud-metrics-export-interval-secs: CLOUD_METRICS_EXPORT_INTERVAL
  prometheus-port: PROMETHEUS_PORT
debug:
  log-mutex: LOG_MUTEX
  exit-on-invariant-violation: EXIT_ON_INVARIANT_VIOLATION
write:
  enable-streaming-writes: STREAMING_WRITES
  global-max-blocks: MAXIMUM_GLOBAL_BLOCKS
read:
  enable-buffered-read: ENABLE_BUFFERED_READ
  global-max-blocks: MAXIMUM_GLOBAL_READ_BLOCKS
profile: PROFILE

Campi del file di configurazione di Cloud Storage FUSE

La tabella seguente descrive i campi che puoi specificare nel file di configurazione di Cloud Storage FUSE. Salvo diversa indicazione, tutti i campi sono facoltativi.

Campo Descrizione Valore valido Valore predefinito
Il nome dell'applicazione del mount. Valore stringa, ad esempio: "my-bucket-mount". ""
Il percorso del file di log in cui verranno scritti i log. Se questo campo non viene specificato, i log vengono indirizzati a stdout quando Cloud Storage FUSE viene eseguito in modalità in primo piano e a syslogs quando Cloud Storage FUSE viene eseguito in modalità in background. Valore stringa, ad esempio: "/var/log". ""
Specifica il formato del file di log.
  • text
  • json
 json

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 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 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
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 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

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 questo campo è disattivato. Questo campo è disattivato per impostazione predefinita.

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. Questo campo deve essere impostato su true se prevedi di eseguire diverse letture casuali o parziali. Valore booleano: true, false false

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 nella cache dei file, consulta Utilizza la memorizzazione nella cache dei file di 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 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 questo campo viene utilizzato, vengono memorizzati nella cache solo i file che corrispondono 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. ""
Specifica il numero massimo di goroutine da generare per file per scaricare l'oggetto da Cloud Storage nella cache dei file. Numero intero 16
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.
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
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 la dimensione di valori di 10 per ogni 6000 file aggiuntivi, dove la cache delle statistiche utilizza in media 1720 byte per file.
  • -1: non imposta alcun limite, per cui la cache delle statistiche utilizza tutta la memoria necessaria.
  • 0: disattiva la cache delle statistiche.
 34

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
Abilita il precaricamento in background dei metadati per gli oggetti all'interno di una directory in caso di fallimento della cache. Questa opzione 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
Monta solo una directory specifica all'interno di un bucket. Un percorso, ad esempio: "/etc/gcsfuse.yaml".
Disabilita l'autenticazione per le richieste. Questo campo deve essere impostato se utilizzi un endpoint personalizzato che non supporta l'autenticazione. Questo campo deve essere impostato anche se utilizzi Cloud Storage FUSE con bucket pubblici. Valore booleano: true, false false
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 URL. Se questo campo non viene impostato, vengono utilizzate le Credenziali predefinite dell'applicazione.
Specifica se riutilizzare il token acquisito da --token-url. Valore booleano: true, false true
Specifica un URL per ottenere un token di accesso quando --key-file non è presente. Un URL.
Specifica un progetto da utilizzare per la fatturazione quando si accede al bucket montato. Questo campo è spesso obbligatorio quando si monta un bucket abilitato con Pagamenti del richiedente. Valore stringa che rappresenta un "ID progetto". ""
Specifica il protocollo utilizzato per comunicare con il backend Cloud Storage. http1
Specifica un endpoint personalizzato alternativo per il recupero dei dati. L'endpoint personalizzato deve supportare le risorse e le operazioni equivalenti all'endpoint JSON di Cloud Storage, storage.UNIVERSE_DOMAIN_NAME:443. Se non viene specificato un endpoint personalizzato, Cloud Storage FUSE utilizza l'endpoint API JSON Cloud Storage globale, storage.googleapis.com:443. Se l'autenticazione non è supportata sull'endpoint personalizzato specificato, imposta il campo anonymous-access su true per bypassare l'autenticazione. Un endpoint, ad esempio: storage.googleapis.com:443.
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, che non specifica alcun timeout
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. "-1", che non specifica alcun limite.
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 numero massimo di connessioni TCP consentite per server. Questo criterio diventa effettivo quando --client-protocol è impostato su http1. 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 TCP. 0
Specifica le dimensioni dei blocchi di dati da scaricare da Cloud Storage, in megabyte (MB). Numero intero compreso tra 1 e 1024. 200
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
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
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 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"
Specifica opzioni di montaggio aggiuntive specifiche del sistema.
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
Consente di rinominare le directory contenenti un numero di discendenti inferiore al limite specificato. Numero intero compreso tra 0 e 2147483647. 0
Specifica un percorso alla directory temporanea in cui vengono eseguite le fasi di scrittura prima del caricamento su Cloud Storage. Un percorso di stringa, ad esempio: "/mnt/ssd/example-user-gcsfuse-temp-dir". "/tmp"
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
Esegue il comando gcsfuse in primo piano. Valore booleano: true, false false
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
Specifica il moltiplicatore per il backoff esponenziale tra tentativi consecutivi. Numero in virgola mobile "2"

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

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

 Numero intero che rappresenta la porta che vuoi specificare. 0
Stampa messaggi di debug quando un mutex viene mantenuto troppo a lungo. Se questo campo è specificato, il livello di gravità dei log viene impostato automaticamente su trace, che include log di traccia, log di debug, log di informazioni, log di avviso e log di errore. Valore booleano: true, false. false
Esce dal programma quando vengono rilevate violazioni delle varianti interne. 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 Letture/Scritture nella documentazione di GitHub di Cloud Storage FUSE. Valore booleano: true, false. true

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
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

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
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.
 ""

Torna all'inizio