Configurare i mount dei volumi Cloud Storage per i servizi Cloud Run

Questa pagina mostra come montare un bucket Cloud Storage come volume di archiviazione, utilizzando i montaggi dei volumi 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

• 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, mentre quella della cache dei tipi è 4 MB.

• Durante la lettura, Cloud Storage FUSE consuma anche memoria diversa dalle cache di stat e di tipo, ad esempio un array di 1 MiB per ogni file letto e per le goroutine.

• Quando si scrive in Cloud Storage, l'intero file viene eseguito il staging nella memoria di Cloud Run prima di essere scritto in Cloud Storage.

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

Per il montaggio come volume è necessario un bucket Cloud Storage.

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:

• Cloud Run Developer (roles/run.developer) sul servizio Cloud Run
• Utente service account (roles/iam.serviceAccountUser) sull'identità di servizio

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 seguente ruolo IAM:

• Amministratore spazio di archiviazione (roles/storage.admin)

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

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM Cloud Run e Autorizzazioni IAM Cloud Run. Se il tuo servizio Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per ulteriori informazioni sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestire l'accesso.

Montare un volume Cloud Storage

Puoi montare più bucket in percorsi di montaggio diversi. Puoi anche montare un volume su più container utilizzando percorsi di montaggio uguali o diversi nei vari container.

Se utilizzi più container, specifica prima i volumi, poi specifica i montaggi dei volumi per ogni container.

I montaggi dei volumi richiedono l'ambiente di esecuzione di seconda generazione. Cloud Run seleziona automaticamente l'ambiente di esecuzione di seconda generazione per il tuo servizio se non ne è stato configurato uno in modo esplicito.

  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"

    template {
      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"
  }

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.

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

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

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

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, YAML o Terraform. Le opzioni di montaggio sono separate da punti e virgole (;) nella Google Cloud CLI e da virgole in YAML, come mostrato nelle seguenti schede:

gcloud beta run services update SERVICE \
    --execution-environment gen2 \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="OPTION_1=VALUE_1;OPTION_N=VALUE_N" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

  resource "google_cloud_run_v2_service" "default" {
    provider = google-beta
    name     = "SERVICE"
    location = "REGION"

    template {
      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
            mount_options = ["OPTION_1=VALUE_1", "OPTION_N=VALUE_N", "OPTION_O"]
        }
      }
    }
  }

Opzioni di montaggio più usate

Le opzioni di montaggio vengono comunemente utilizzate per:

• Configura impostazioni cache
• Montare 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 del volume impostando le opzioni di montaggio correlate alla memorizzazione nella cache. La tabella seguente elenca le impostazioni, insieme ai valori predefiniti di Cloud Run :

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:

gcloud beta run services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="metadata-cache-ttl-secs=120;stat-cache-max-size-mb=52;type-cache-max-size-mb=7" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Sostituisci:

• SERVICE con il nome del tuo servizio.
• VOLUME_NAME con il nome che preferisci per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
• BUCKET_NAME con il nome del tuo bucket Cloud Storage.
• MOUNT_PATH con il percorso relativo in cui stai montando il volume, ad esempio /cache.

Attiva il logging di debug

Per impostazione predefinita, Cloud Storage FUSE registra gli eventi con gravità 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à avseverity 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.

La seguente riga di comando attiva il logging di debug:

gcloud beta run services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Sostituisci:

• SERVICE con il nome del tuo servizio.
• VOLUME_NAME con il nome che preferisci per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
• BUCKET_NAME con il nome del tuo bucket Cloud Storage.
• MOUNT_PATH con il percorso relativo in cui stai montando il volume, ad esempio /cache.

Disabilita directory implicite

Per far sembrare Cloud Storage più simile a un file system standard, Cloud Run attiva 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 disattivazione delle directory implicite può migliorare le prestazioni e 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 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 i costi dell'applicazione. Per saperne di più, leggi la documentazione di Cloud Storage FUSE relativa a file e directory.

La seguente riga di comando disattiva le directory implicite:

gcloud beta run services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Sostituisci:

• SERVICE con il nome del tuo servizio.
• VOLUME_NAME con il nome che preferisci per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
• BUCKET_NAME con il nome del tuo bucket Cloud Storage.
• MOUNT_PATH con il percorso relativo in cui stai montando il volume, ad esempio /cache.

Montare una directory specifica all'interno del bucket Cloud Storage

Per impostazione predefinita, Cloud Run monta l'intero bucket Cloud Storage, il che consente ai servizi 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 implementare questa soluzione per scopi di isolamento, quando hai bisogno che servizi diversi abbiano accesso a directory diverse nel bucket di archiviazione.

La seguente riga di comando specifica la directory da montare:

gcloud beta run services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Sostituisci:

• SERVICE con il nome del tuo servizio.
• VOLUME_NAME con il nome che preferisci per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
• BUCKET_NAME con il nome del tuo bucket Cloud Storage.
• MOUNT_PATH con il percorso relativo in cui stai montando il volume, ad esempio /cache.

Imposta il volume 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 services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Sostituisci:

• SERVICE con il nome del tuo servizio.
• VOLUME_NAME con il nome che preferisci per il volume. Il valore VOLUME_NAME viene utilizzato per mappare il volume al punto di montaggio del volume.
• BUCKET_NAME con il nome del tuo bucket Cloud Storage.
• MOUNT_PATH con il percorso relativo in cui stai montando il volume, ad esempio /cache.

Visualizzare le impostazioni dei punti di montaggio del volume

Ottimizzazione delle prestazioni della larghezza di banda di rete di Cloud Storage FUSE

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

• Attiva l'accesso privato Google, assicurandoti di impostare il parametro vpc-egress su all-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 verrà montato e il servizio Cloud Run non verrà avviato. Inoltre, se Cloud Storage FUSE impiega più di 30 secondi per il montaggio, il servizio Cloud Run non verrà avviato 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 avvengono in parallelo.

Le operazioni che utilizzano Cloud Storage FUSE sono influenzate dalla larghezza di banda di rete perché Cloud Storage FUSE comunica con Cloud Storage utilizzando l'API Cloud 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:

• Documentazione di Cloud Storage FUSE
• Prestazioni di Cloud Storage FUSE
• Semantica di Cloud Storage FUSE

Cancella e rimuovi volumi e montaggi dei volumi

Puoi cancellare tutti i volumi e i relativi punti di montaggio oppure rimuovere singoli volumi e i relativi punti di montaggio.

Cancella tutti i volumi e i relativi punti di montaggio

Per cancellare tutti i volumi e i montaggi dei volumi dal servizio a singolo container, esegui questo comando:

gcloud run services update SERVICE \
    --clear-volumes
    --clear-volume-mounts

Se hai più container, segui le convenzioni della CLI sidecar per cancellare i volumi e i montaggi dei volumi:

gcloud run services update SERVICE \
    --container=container1 \
    --clear-volumes
    -–clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    -–clear-volume-mounts

Rimuovere singoli volumi e montaggi di volumi

Per rimuovere un volume, devi rimuovere anche tutti i relativi montaggi.

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

gcloud run services update SERVICE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH