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 richiamate laddove 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 container devono essere compilati per Linux a 64 bit. Cloud Run supporta in modo specifico il formato ABI x86_64 di Linux.

Cloud Run accetta immagini container nei formati di immagine Docker Image Manifest V2, Schema 1, Schema 2 e OCI.

Se esegui il deployment di un'immagine multi-architettura, l'elenco dei manifest deve includere linux/amd64.

Ascolto delle richieste sulla porta corretta (servizi)

Un servizio Cloud Run avvia le istanze di Cloud Run per gestire le richieste in entrata. Un'istanza Cloud Run ha sempre un singolo container in entrata e, facoltativamente, uno o più container collaterali. I seguenti dettagli di configurazione della porta si applicano solo al container in entrata, non ai file collaterali.

Il container in entrata all'interno di un'istanza deve rimanere in ascolto delle 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 per inviare le richieste alla porta che preferisci. Cloud Run inserisce la variabile di ambiente PORT nel container in entrata.

Il container in esecuzione in un'esecuzione di job deve essere chiuso al completamento

Per i job Cloud Run, il container deve uscire con il codice di uscita 0 quando il job è stato completato correttamente e con un codice di uscita diverso da zero quando il job non è riuscito.

Poiché i job non dovrebbero gestire le richieste, il container non deve rimanere in ascolto su una porta o avviare un server web.

Crittografia a livello di trasporto (TLS)

Il container non deve implementare direttamente il protocollo TLS (Transport Layer Security). TLS è terminato da Cloud Run per HTTPS e gRPC, quindi le richieste vengono inviate tramite proxy come HTTP/1 o gRPC al container senza TLS.

Se configuri un servizio Cloud Run per l'utilizzo end-to-end HTTP/2, il container deve gestire le richieste in formato di testo in chiaro HTTP/2 (h2c), poiché il protocollo TLS viene comunque interrotto 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.

Variabili di ambiente

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

Variabili di ambiente per i servizi

Le seguenti variabili di ambiente vengono aggiunte automaticamente a tutti i container in esecuzione, ad eccezione di PORT. La variabile PORT viene aggiunta solo al container in entrata:

Nome	Descrizione	Esempio
PORT	La porta su cui il server HTTP deve rimanere in ascolto.	8080
K_SERVICE	Il nome del servizio Cloud Run in esecuzione.	hello-world
K_REVISION	Il nome della revisione di 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 sono 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 di Cloud Run in esecuzione.	hello-world-abc
CLOUD_RUN_TASK_INDEX	L'indice di questa attività. Inizia da 0 per la prima attività e incrementa di 1 per ogni attività successiva, fino al numero massimo di attività meno 1. Se imposti --parallelism su un valore superiore a 1, le attività potrebbero non seguire l'ordine dell'indice. Ad esempio, l'attività 2 potrebbe iniziare prima dell'attività 1.	0
CLOUD_RUN_TASK_ATTEMPT	Il numero di nuovi tentativi di questa attività. Inizia da 0 per il primo tentativo e incrementa di 1 per ogni nuovo tentativo successivo, fino al valore massimo dei nuovi tentativi.	0
CLOUD_RUN_TASK_COUNT	Il numero di attività definite nel parametro --tasks.	1

Requisiti dell'intestazione di richiesta e risposta (servizi)

Per i servizi Cloud Run, i nomi delle intestazioni sono limitati a caratteri ASCII stampabili non vuoti e non possono contenere i due punti. I valori di intestazione sono limitati a caratteri ASCII visibili più spazio e tabulazione orizzontale come previsto dallo standard IETF RFC 7230

Accesso al file system

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

• Poiché si tratta di un file system in memoria, la scrittura in questo file utilizza la memoria dell'istanza.
• I dati scritti nel file system non vengono mantenuti quando l'istanza viene arrestata.

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, causando un arresto anomalo dell'istanza. Puoi evitare questo problema se utilizzi un volume in memoria dedicato con un limite di dimensioni.

Ciclo di vita dell'istanza

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

Per i servizi

Quanto segue si applica solo ai servizi.

Scalabilità del servizio

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

Ogni istanza esegue un numero fisso di container: un container in entrata e, facoltativamente, uno o più container collaterali.

Quando una revisione non riceve traffico, viene fatto lo scale in del numero minimo di istanze configurate (zero per impostazione predefinita).

Avvio

Per i servizi Cloud Run, le istanze devono rimanere in ascolto delle richieste entro 4 minuti dall'avvio e tutti i container all'interno dell'istanza devono essere integri. Durante questo tempo di avvio, alle istanze viene allocata la CPU. Puoi abilitare 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 container in entrata non appena sarà in ascolto sulla porta configurata.

Una richiesta in attesa di un'istanza viene mantenuta in attesa in una coda come segue:

• Se vengono avviate nuove istanze, ad esempio durante uno scale out, le richieste cadranno almeno per il tempo di avvio medio delle istanze di container di questo servizio. Questo include quando la richiesta avvia uno scale out, ad esempio quando viene scalato da zero.
• Se il tempo di avvio è inferiore a 10 secondi, le richieste verranno sospese per un massimo di 10 secondi.
• Se non sono presenti istanze in fase di avvio e la richiesta non avvia uno scale out, le richieste verranno sospese per un massimo di 10 secondi.

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

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

Elaborazione di una richiesta

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

Inattiva

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.

Chiusura

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 elabora le richieste deve essere arrestata, le nuove richieste in entrata vengono instradate ad altre istanze e viene concesso il tempo di completamento per le richieste attualmente in fase di elaborazione. In casi eccezionali, Cloud Run potrebbe avviare un arresto e inviare un segnale SIGTERM a un container che è ancora in fase di elaborazione delle 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 fatturata. Nei servizi che utilizzano l'ambiente di esecuzione di prima generazione, se l'istanza non esegue il trappole dell'indicatore SIGTERM, viene arrestato immediatamente. Consulta gli esempi di codice per scoprire come eseguire il trap del segnale SIGTERM.

Chiusura forzata

Se uno o più container Cloud Run superano il limite totale di memoria dei container, l'istanza viene terminata. Tutte le richieste ancora in fase di elaborazione sull'istanza con un errore HTTP 500.

Per lavori

Per i job Cloud Run, le istanze di container vengono eseguite fino alla chiusura dell'istanza di container, fino al raggiungimento del timeout dell'attività o fino all'arresto anomalo del container.

Chiusura forzata

Un'istanza di container Cloud Run che supera il limite di memoria consentito viene terminata. Tutte le richieste ancora in fase di elaborazione sull'istanza di container 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'avvio effettivo dell'arresto, a quel punto Cloud Run invia un segnale SIGKILL, arrestando l'istanza di container.

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

Consulta l'esempio di codice SIGTERM per scoprire come eseguire il trap del segnale SIGTERM.

Risorse delle istanze di container

CPU

A ogni container Cloud Run di un'istanza viene allocata per impostazione predefinita la vCPU che è stata configurata (1 per impostazione predefinita). È possibile configurare i limiti della CPU su ogni container separatamente.

Una vCPU viene implementata come astrazione dell'hardware sottostante per fornire il tempo di CPU approssimativo equivalente a un singolo hyperthread hardware su piattaforme CPU variabili. Tutte le piattaforme CPU utilizzate da Cloud Run supportano il set di istruzione AVX2. Tieni presente che il contratto del container non contiene dettagli aggiuntivi sulla piattaforma CPU.

Il container può essere eseguito su più core contemporaneamente.

Per i servizi Cloud Run, puoi specificare la CPU da allocare sempre durante la vita dell'istanza o da allocare solo durante l'avvio dell'istanza e l'elaborazione delle richieste. Per maggiori dettagli, consulta Allocazione della CPU.

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

Puoi abilitare il booster 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 container Cloud Run viene allocata la memoria configurata (512 MiB per impostazione predefinita). È possibile configurare i limiti di memoria su ogni container separatamente.

Utilizzi tipici della memoria includono:

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

Contemporaneità (servizi)

Per i servizi Cloud Run, per impostazione predefinita ogni istanza di Cloud Run è impostata su più contemporaneità, in cui il container in entrata può ricevere più di una richiesta contemporaneamente. Puoi modificare questa impostazione impostando la contemporaneità.

Sandbox container

Se utilizzi l'ambiente di esecuzione di prima generazione, i container Cloud Run vengono limitati tramite sandbox utilizzando la sandbox per il runtime dei container gVisor. Come documentato nel riferimento sulla compatibilità delle chiamate di sistema 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 di 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 di processo separato, quindi inizia come processo di inizializzazione del container con una semantica del processo speciale. Nell'ambiente di esecuzione di prima generazione, il codice di servizio non viene eseguito come processo di inizializzazione del container.

Server di metadati dell'istanza

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

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

Nella tabella seguente sono elencate alcune delle informazioni relative al 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 di progetto a cui appartiene il servizio o il job Cloud Run
/computeMetadata/v1/instance/region	La regione di questo servizio o job Cloud Run restituisce projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id	Identificatore univoco dell'istanza (disponibile anche nei log).
/computeMetadata/v1/instance/service-accounts/default/email	Email per l'identità del servizio di questo servizio o 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 sono in esecuzione le istanze. Di conseguenza, l'attributo dei metadati /computeMetadata/v1/instance/zone restituisce sempre projects/PROJECT-NUMBER/zones/REGION-1.

Nomi file

I nomi di file che utilizzi nei contenitori devono essere compatibili con UTF-8, ovvero UTF-8 o con un nome che possa essere convertito automaticamente in UTF-8 in modo sicuro. Se i nomi dei tuoi file utilizzano codifiche diverse, esegui Docker build su una macchina con nomi file compatibili con UTF-8 ed evita di copiare i file in un container che contiene nomi UTF-8 incompatibili.

Il deployment del container non riesce se i nomi dei file non sono compatibili con UTF-8. Tieni presente che non ci sono limitazioni alla codifica dei caratteri utilizzata all'interno di un file.

Connessioni in uscita

Timeout delle richieste in uscita

Per i servizi e i job Cloud Run, viene impostato un timeout dopo 10 minuti di inattività per le richieste dal container al VPC. Per le richieste dal container a internet, viene conteggiato un timeout dopo 20 minuti di inattività.

La connessione in uscita viene reimpostata

I flussi di connessioni dal container verso il VPC e su internet possono a volte essere terminati e sostituiti quando l'infrastruttura sottostante viene riavviata o aggiornata. Se l'applicazione riutilizza connessioni di lunga durata, ti consigliamo di configurare l'applicazione in modo da ristabilire le connessioni per evitare il riutilizzo di una connessione non più disponibile.