Contratto runtime container

Questa pagina elenca i requisiti e i comportamenti chiave dei container in Cloud Run. Esistono alcune differenze tra i servizi Cloud Run e i job Cloud Run: queste sono indicate ove opportuno.

Lingue e immagini supportate

L'immagine container può eseguire codice scritto nel linguaggio di programmazione di tua scelta e utilizzare qualsiasi immagine di base, a condizione che rispetti i vincoli elencati in questa pagina.

Gli eseguibili nell'immagine del contenitore devono essere compilati per Linux a 64 bit. Cloud Run supporta in modo specifico il formato ABI x86_64 Linux.

Cloud Run accetta immagini container nel manifest dell'immagine Docker V2, schema 1, schema 2 e OCI. Cloud Run accetta anche immagini container compresse con Zstd.

Se esegui il deployment di un'immagine multipiattaforma, l'elenco manifest deve includere linux/amd64.

Per le funzioni di cui è stato eseguito il deployment con Cloud Run, puoi utilizzare una delle immagini di base del runtime Cloud Run pubblicate dai buildpack di Google Cloud per ricevere aggiornamenti automatici di sicurezza e manutenzioni. Consulta il programma di supporto del runtime per conoscere i runtime supportati.

Ascolto delle richieste sulla porta corretta (servizi)

Un servizio Cloud Run avvia istanze Cloud Run per gestire le richieste in entrata. Un'istanza Cloud Run ha sempre un unico container di ingresso in ascolto delle richieste e, facoltativamente, uno o più container sidecar. I seguenti dettagli di configurazione delle porte si applicano solo al contenitore di ingresso, non ai sidecar.

Il contenitore di ingresso all'interno di un'istanza deve ascoltare le richieste su 0.0.0.0 sulla porta a cui vengono inviate le richieste. Per impostazione predefinita, le richieste vengono inviate a 8080, ma puoi configurare Cloud Run in modo da inviare le richieste alla porta che preferisci. Cloud Run inserisce la variabile di ambiente PORT nel container di ingresso.

Il contenitore in esecuzione nell'esecuzione di un job deve uscire al termine

Per i job Cloud Run, il contenitore deve uscire con il codice di uscita 0 quando il job è stato completato correttamente ed uscire con un codice di uscita diverso da zero quando il job ha avuto esito negativo.

Poiché i job non devono gestire le richieste, il contenitore non deve ascoltare su una porta o avviare un server web.

Crittografia del livello di trasporto (TLS)

Il contenitore non deve implementare direttamente alcuna sicurezza del livello di trasporto. TLS viene terminato da Cloud Run per HTTPS e gRPC, quindi le richieste vengono proxy come HTTP/1 o gRPC al contenitore senza TLS.

Se configuri un servizio Cloud Run per utilizzare HTTP/2 end-to-end, il contenitore deve gestire le richieste in formato HTTP/2 in chiaro (h2c), perché TLS viene comunque terminato automaticamente da Cloud Run.

Risposte (servizi)

Per i servizi Cloud Run, il container deve inviare una risposta entro il tempo specificato nell'impostazione di timeout della richiesta dopo aver ricevuto una richiesta, incluso il tempo di avvio del container. In caso contrario, la richiesta viene terminata e viene restituito un errore 504.

Memorizzazione nella cache delle risposte e cookie

Se la risposta del servizio Cloud Run contiene un'intestazione Set-Cookie, Cloud Run imposta l'intestazione Cache-Control su private in modo che la risposta non venga memorizzata nella cache. In questo modo, gli altri utenti non possono recuperare il cookie.

Variabili di ambiente

Per i servizi e i job Cloud Run sono disponibili diversi insiemi di variabili di ambiente.

Variabili di ambiente per i servizi

Le seguenti variabili di ambiente vengono aggiunte automaticamente a tutti i contenitori in esecuzione, tranne PORT. La variabile PORT viene aggiunta solo al contenitore di importazione:

Nome	Descrizione	Esempio
PORT	La porta su cui deve rimanere in ascolto il server HTTP.	8080
K_SERVICE	Il nome del servizio Cloud Run in esecuzione.	hello-world
K_REVISION	Il nome della revisione Cloud Run in esecuzione.	hello-world.1
K_CONFIGURATION	Il nome della configurazione Cloud Run che ha creato la revisione.	hello-world

Variabili di ambiente per i job

Per i job Cloud Run, vengono impostate le seguenti variabili di ambiente:

Nome	Descrizione	Esempio
CLOUD_RUN_JOB	Il nome del job Cloud Run in esecuzione.	hello-world
CLOUD_RUN_EXECUTION	Il nome dell'esecuzione Cloud Run in esecuzione.	hello-world-abc
CLOUD_RUN_TASK_INDEX	L'indice di questa attività. Inizia da 0 per la prima attività e aumenta di 1 per ogni attività successiva, fino al numero massimo di attività meno 1. Se imposti --parallelism su un valore maggiore di 1, le attività potrebbero non seguire l'ordine dell'indice. Ad esempio, sarebbe possibile avviare l'attività 2 prima dell'attività 1.	0
CLOUD_RUN_TASK_ATTEMPT	Il numero di volte in cui è stato eseguito un nuovo tentativo per questa attività. Inizia da 0 per il primo tentativo e aumenta di 1 per ogni tentativo successivo, fino al valore massimo dei tentativi.	0
CLOUD_RUN_TASK_COUNT	Il numero di attività definite nel parametro --tasks.	1

Requisiti per le intestazioni di richiesta e risposta (servizi)

Per i servizi Cloud Run, i nomi delle intestazioni sono limitati ai caratteri ASCII stampabili diversi dagli spazi e non possono contenere i due punti. I valori delle intestazioni sono limitati ai caratteri ASCII visibili, oltre a spazi e tabulazioni orizzontali, come da IETF RFC 7230

Accesso al file system

Il file system in ciascuno dei tuoi container è scrivibile ed è soggetto al seguente comportamento:

• Si tratta di un file system in memoria, quindi la scrittura utilizza la memoria dell'istanza.
• I dati scritti nel file system non vengono conservati quando l'istanza viene interrotta.

Tieni presente che non puoi specificare un limite di dimensioni per questo file system, quindi puoi potenzialmente utilizzare tutta la memoria allocata all'istanza scrivendo nel file system in memoria, causandone l'arresto anomalo. Puoi evitare questo problema se utilizzi un volume in memoria con un limite di dimensioni.

Ciclo di vita dell'istanza

Le caratteristiche del ciclo di vita sono diverse per i job e i servizi Cloud Run, pertanto vengono descritte separatamente nelle sezioni seguenti.

Per i servizi

Quanto segue si applica solo ai servizi.

Scalabilità del servizio

Un servizio Cloud Run viene scalato automaticamente al numero di istanze necessarie per gestire tutte le richieste, gli eventi o l'utilizzo della CPU in entrata.

Ogni istanza esegue un numero fisso di container: un container di ingresso e, facoltativamente, uno o più container sidecar.

Quando una revisione non riceve traffico, viene scalata in base al numero minimo di istanze configurate (zero per impostazione predefinita).

Avvio

Per i servizi Cloud Run, le istanze devono ascoltare le richieste entro 4 minuti dall'avvio e tutti i container all'interno dell'istanza devono essere operativi. Durante questo tempo di avvio, alle istanze viene allocata la CPU. Puoi attivare il boosting della CPU all'avvio per aumentare temporaneamente l'allocazione della CPU durante l'avvio dell'istanza in modo da ridurre la latenza di avvio.

Le richieste verranno inviate al contenitore di ingresso non appena è in ascolto sulla porta configurata.

Una richiesta in attesa di un'istanza verrà mantenuta in sospeso in una coda come segue:

• Se vengono avviate nuove istanze, ad esempio durante uno scaling out, le richieste rimarranno in attesa per almeno il tempo di avvio medio delle istanze di container di questo servizio. Ciò include quando la richiesta avvia uno scale-out, ad esempio quando si esegue lo scale up da zero.
• Se il tempo di avvio è inferiore a 10 secondi, le richieste rimarranno in attesa per un massimo di 10 secondi.
• Se non sono in corso l'avvio di istanze e la richiesta non avvia un'operazione di scalabilità, le richieste rimarranno in attesa per un massimo di 10 secondi.

Puoi configurare un probe di avvio per determinare se il contenitore è stato avviato ed è pronto a gestire le richieste.

Per un servizio Cloud Run composto da istanze multi-container, puoi specificare la sequenza in cui vengono avviati i container all'interno dell'istanza configurando l'ordine di avvio dei container.

Elaborazione di una richiesta

Per i servizi Cloud Run, la CPU viene sempre allocata a tutti i container, inclusi i sidecar, all'interno di un'istanza, purché la revisione Cloud Run stia elaborando almeno una richiesta.

Inattivo

Per i servizi Cloud Run, un'istanza inattiva è quella che non elabora alcuna richiesta.

La CPU allocata a tutti i container in un'istanza inattiva dipende dall'allocazione della CPU configurata.

A meno che un'istanza non debba essere mantenuta inattiva a causa dell'impostazione di configurazione del numero minimo di istanze, non verrà mantenuta inattiva per più di 15 minuti.

Arresto

Per i servizi Cloud Run, un'istanza inattiva può essere arrestata in qualsiasi momento, incluse le istanze mantenute in uso tramite un numero minimo di istanze. Se un'istanza che sta elaborando richieste deve essere arrestata, le nuove richieste in arrivo vengono inoltrate ad altre istanze e alle richieste in fase di elaborazione viene concesso il tempo per il completamento. In casi eccezionali, Cloud Run potrebbe avviare un arresto e inviare un segnale SIGTERM a un container che sta ancora elaborando le richieste.

Prima di arrestare un'istanza, Cloud Run invia un segnale SIGTERM a tutti i container di un'istanza, indicando l'inizio di un periodo di 10 secondi prima dell'arresto effettivo, a quel punto Cloud Run invia un segnale SIGKILL. Durante questo periodo, all'istanza viene allocata la CPU e viene addebitato il relativo costo. Nei servizi che utilizzano l'ambiente di esecuzione di prima generazione, se l'istanza non intercetta il segnale SIGTERM, viene immediatamente arrestata. Consulta gli esempi di codice per scoprire come intercettare il segnale SIGTERM.

Interruzione forzata

Se uno o più container Cloud Run superano il limite di memoria totale del contenitore, l'istanza viene interrotta. Tutte le richieste in fase di elaborazione nell'istanza terminano con un errore HTTP 500.

Per le offerte di lavoro

Per i job Cloud Run, le istanze container vengono eseguite fino all'uscita dell'istanza container, fino al raggiungimento del timeout della task o fino al crash del container.

Interruzione forzata

Un'istanza del contenitore Cloud Run che supera il limite di memoria consentito viene interrotta. Tutte le richieste ancora in elaborazione nell'istanza del contenitore terminano con un errore HTTP 500.

Se un'attività supera il timeout dell'attività, Cloud Run invia un segnale "SIGTERM" che indica l'inizio di un periodo di 10 secondi prima dell'arresto effettivo, a quel punto Cloud Run invia un segnale SIGKILL che arresta l'istanza del contenitore.

Durante questo periodo, alle istanze container viene allocata la CPU per l'intero ciclo di vita e vengono fatturate.

Consulta il codice di esempio SIGTERM per scoprire come intercettare l'indicatore SIGTERM.

Risorse delle istanze di container

CPU

Per impostazione predefinita, a ogni contenitore Cloud Run in un'istanza viene allocata la vCPU che è stata configurata (1 per impostazione predefinita). È possibile configurare i limiti della CPU su ciascun contenitore separatamente.

Una vCPU viene implementata come un'astrazione dell'hardware sottostante per fornire il tempo della CPU approssimativo equivalente di un singolo hyperthread hardware su piattaforme CPU variabili. Tutte le piattaforme CPU utilizzate da Cloud Run supportano l'insieme di istruzioni AVX2. Tieni presente che il contratto del contenitore non contiene ulteriori dettagli sulla piattaforma CPU.

Il contenitore potrebbe essere eseguito su più core contemporaneamente.

Per i servizi Cloud Run, puoi specificare che la CPU venga allocata sempre durante la vita dell'istanza o solo durante l'avvio dell'istanza e l'elaborazione delle richieste. Per informazioni dettagliate, consulta la sezione Allocazione della CPU.

Se hai configurato un numero di istanze minime, queste sono soggette anche alla configurazione dell'allocazione della CPU.

Puoi attivare il boosting della CPU all'avvio per aumentare temporaneamente l'allocazione della CPU durante l'avvio dell'istanza in modo da ridurre la latenza di avvio.

Memoria

Per impostazione predefinita, a ogni contenitore Cloud Run viene allocata la memoria configurata (512 MiB per impostazione predefinita). È possibile configurare i limiti di memoria su ciascun contenitore separatamente.

Gli utilizzi tipici della memoria includono:

• Codice caricato nella memoria per eseguire il servizio
• Scrittura nel file system
• Processi aggiuntivi in esecuzione nel contenitore, ad esempio un server nginx
• Sistemi di memorizzazione nella cache in memoria come OpCache di PHP
• Utilizzo della memoria per richiesta
• Volumi in memoria condivisi

GPU

Puoi configurare un contenitore in un'istanza Cloud Run per accedere a una GPU. Se il servizio Cloud Run viene eseguito con i container sidecar, solo un container nel deployment può accedere alla GPU. Per requisiti e dettagli, consulta Configurare la GPU.

Librerie NVIDIA

Per impostazione predefinita, tutte le librerie dei driver NVIDIA L4 sono montate in/usr/local/nvidia/lib64.

Se il servizio non riesce a trovare le librerie fornite, aggiorna il percorso di ricerca per il linker dinamico aggiungendo la riga ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} al tuo Dockerfile.

Tieni presente che puoi anche impostare LD_LIBRARY_PATH come variabile di ambiente per il servizio Cloud Run, se hai un'immagine esistente e non vuoi ricostruirla con un Dockerfile aggiornato.

Se vuoi utilizzare una versione di CUDA successiva alla 12.2, il modo più semplice è fare affidamento su una immagine di base NVIDIA più recente con i pacchetti di compatibilità futura già installati. Un'altra opzione è installare manualmente i pacchetti di compatibilità futura di NVIDIA e aggiungerli a LD_LIBRARY_PATH. Consulta la matrice di compatibilità di NVIDIA per determinare quali versioni di CUDA sono compatibili con le versioni successive del driver NVIDIA fornito (535.129.03).

Concorrenza (servizi)

Per i servizi Cloud Run, per impostazione predefinita ogni istanza Cloud Run è impostata su più contemporaneità, in cui il contenitore di ingresso può ricevere più richieste contemporaneamente. Puoi modificare questo valore impostando la concorrenza.

Sandbox del contenitore

Se utilizzi l'ambiente di esecuzione di prima generazione, i container Cloud Run vengono inseriti in una sandbox utilizzando la sandbox del runtime del container gVisor. Come documentato nella documentazione di riferimento sulla compatibilità delle chiamate di sistema di gVisor, alcune chiamate di sistema potrebbero non essere supportate da questa sandbox del contenitore.

Se utilizzi l'ambiente di esecuzione di seconda generazione, hai la compatibilità completa con Linux. I job Cloud Run utilizzano sempre l'ambiente di esecuzione di seconda generazione. Nell'ambiente di esecuzione di seconda generazione, /sys/class/dmi/id/product_name è impostato su Google Compute Engine.

L'ambiente di esecuzione di seconda generazione esegue il codice di servizio in uno spazio dei nomi del processo distinto, quindi inizia come processo di inizializzazione del contenitore con una semantica del processo speciale. Nell'ambiente di esecuzione di prima generazione, il codice del servizio non viene eseguito come processo di inizializzazione del contenitore.

Server di metadati dell'istanza

Le istanze Cloud Run espongono un server di metadati che puoi utilizzare per recuperare i dettagli dei tuoi container, ad esempio l'ID progetto, la regione, l'ID istanza o gli account di servizio. Puoi anche utilizzare il server dei metadati per generare token per l'identità del servizio.

Per accedere ai dati del server di metadati, utilizza le richieste HTTP all'endpoint http://metadata.google.internal/ con l'intestazione Metadata-Flavor: Google: non sono necessarie librerie client. Per ulteriori informazioni, consulta la sezione Ottenere i metadati.

La tabella seguente elenca alcune delle informazioni del server dei metadati disponibili:

Percorso	Descrizione
/computeMetadata/v1/project/project-id	ID progetto del progetto a cui appartiene il servizio o il job Cloud Run
/computeMetadata/v1/project/numeric-project-id	Numero del progetto a cui appartiene il servizio o il job Cloud Run
/computeMetadata/v1/instance/region	Regione di questo servizio o job Cloud Run, restituisce projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id	Identificatore univoco dell'istanza (disponibile anche in logs).
/computeMetadata/v1/instance/service-accounts/default/email	Indirizzo email per l'identità del servizio o del job Cloud Run.
/computeMetadata/v1/instance/service-accounts/default/token	Genera un token di accesso OAuth2 per l'account di servizio di questo servizio o job Cloud Run. L'agente di servizio Cloud Run viene utilizzato per recuperare un token. Questo endpoint restituirà una risposta JSON con un attributo access_token. Scopri di più su come estrarre e utilizzare questo token di accesso.

Tieni presente che Cloud Run non fornisce dettagli sulla zona Google Cloud in cui vengono eseguite le istanze. Di conseguenza, l'attributo dei metadati /computeMetadata/v1/instance/zone restituisce sempre projects/PROJECT-NUMBER/zones/REGION-1.

Nomi file

I nomi dei file utilizzati nei contenitori devono essere compatibili con UTF-8, in formato UTF-8 o in un formato che possa essere convertito automaticamente in UTF-8 in modo sicuro. Se i nomi dei file utilizzano codificazioni diverse, esegui Docker Build su una macchina con nomi di file compatibili con UTF-8 ed evita di copiare i file in un contenitore che contiene nomi UTF-8 incompatibili.

Il deployment del contenitore non va a buon fine se i nomi dei file non sono compatibili con UTF-8. Tieni presente che non esistono limitazioni per la codifica dei caratteri utilizzata all'interno di un file.

Connessioni in uscita

Tempo di attesa delle richieste in uscita

Per i servizi e i job Cloud Run, è previsto un timeout dopo 10 minuti di inattività per le richieste dal contenitore al VPC. Per le richieste dal contenitore a internet, è previsto un timeout dopo 20 minuti di inattività.

Reimpostazione delle connessioni in uscita

Gli stream di connessione dal contenitore alla VPC e a internet possono essere talvolta interrotti e sostituiti quando l'infrastruttura sottostante viene riavviata o aggiornata. Se la tua applicazione riutilizza connessioni di lunga durata, ti consigliamo di configurarla in modo da ristabilire le connessioni per evitare il riutilizzo di una connessione non attiva.