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: vengono indicate dove appropriato.
Lingue e immagini supportate
L'immagine container può eseguire codice scritto nel linguaggio di programmazione che preferisci 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 specificamente il formato Linux x86_64 ABI.
Cloud Run accetta immagini container nei formati immagine Docker manifest V2, Schema 1, Schema 2 e OCI.
Se esegui il deployment di un'immagine con più architetture,
l'elenco manifest
deve includere linux/amd64
.
In 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 che rimane in ascolto delle richieste e, facoltativamente, uno o più container collaterali. I seguenti dettagli di configurazione delle porte si applicano solo al container in entrata, non ai file collaterali.
Il container in entrata 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
in modo che invii le richieste alla porta che preferisci. Cloud Run inserisce la variabile di ambiente PORT
nel container in entrata.
Il container in esecuzione nell'esecuzione di un job deve chiudersi 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 riesce.
Dato che i job non devono gestire le richieste, il container non deve rimanere in ascolto su una porta o avviare un server web.
Crittografia TLS
Il container non deve implementare alcuna sicurezza del livello di trasporto direttamente. TLS viene terminato da Cloud Run per HTTPS e gRPC, quindi le richieste vengono inviate tramite proxy al container senza TLS come HTTP/1 o gRPC.
Se configuri un servizio Cloud Run in modo che utilizzi HTTP/2 end-to-end, il container deve gestire le richieste in formato HTTP/2 cleartext (h2c), perché il protocollo 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 tuo 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 i cookie.
Variabili di ambiente
Sono disponibili diversi set di variabili di ambiente per i servizi e i job Cloud Run.
Variabili di ambiente per i servizi
Le seguenti variabili di ambiente vengono aggiunte automaticamente a tutti i container in esecuzione, tranne 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 maggiore di 1, le attività potrebbero non seguire l'ordine dell'indice. Ad esempio, l'attività 2 potrebbe essere avviata prima dell'attività 1. |
0 |
CLOUD_RUN_TASK_ATTEMPT |
Il numero di nuovi tentativi per 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à definito nel parametro --tasks . |
1 |
Requisiti delle intestazioni di richiesta e risposta (servizi)
Per i servizi Cloud Run, i nomi delle intestazioni sono limitati a caratteri ASCII non spazi vuoti stampabili e non possono contenere due punti. I valori dell'intestazione sono limitati a caratteri ASCII visibili più spazio e tabulazione orizzontale secondo lo standard IETF RFC 7230
Accesso al file system
Il file system in ciascuno dei tuoi container è scrivibile ed è soggetto al seguente comportamento:
- Poiché si tratta di un file system in memoria, per la scrittura viene utilizzata 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 per le dimensioni di questo file system, quindi puoi potenzialmente utilizzare tutta la memoria allocata all'istanza scrivendo sul file system in memoria. Questo comporterà l'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 i job e i servizi Cloud Run, perciò sono descritte separatamente nelle sottosezioni seguenti.
Per i servizi
Le seguenti indicazioni sono valide solo per i 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 delle 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 scalato al 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 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.
Le richieste verranno inviate al container in entrata non appena è in ascolto sulla porta configurata.
Una richiesta in attesa di un'istanza rimarrà in attesa in una coda come segue:
- Se vengono avviate nuove istanze, ad esempio durante uno scale out, le richieste pendono almeno per il tempo di avvio medio delle istanze di container di questo servizio. Sono inclusi i casi in cui la richiesta avvia uno scale out, ad esempio quando viene scalato da zero.
- Se il tempo di avvio è inferiore a 10 secondi, le richieste dureranno fino a 10 secondi.
- Se non sono presenti istanze in fase di avvio e la richiesta non avvia uno scale out, le richieste dureranno fino a 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 costituito da istanze multi-container, puoi specificare la sequenza in cui i container vengono avviati all'interno dell'istanza configurando l'ordine di avvio del container.
Elaborazione di una richiesta
Per i servizi Cloud Run, la CPU viene sempre allocata a tutti i container, inclusi i file collaterali all'interno di un'istanza, purché la revisione di Cloud Run elabori almeno una richiesta
Inattivo
Per i servizi Cloud Run, un'istanza inattiva è una istanza 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 tenuta inattiva a causa dell'impostazione di configurazione del numero minimo di istanze, non verrà tenuta 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 sta elaborando le richieste deve essere arrestata, le nuove richieste in entrata vengono instradate ad altre istanze e le richieste attualmente in fase di elaborazione hanno il tempo di essere completate. 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 in un'istanza,
indicando l'inizio di un periodo di 10 secondi
prima dell'arresto effettivo, dopodiché Cloud Run invia un segnale SIGKILL
.
Durante questo periodo, all'istanza viene allocata la CPU e viene fatturato il relativo importo.
Nei servizi che utilizzano l'ambiente di esecuzione di prima generazione, se l'istanza non intercetta l'indicatore SIGTERM
, viene arrestata immediatamente. Fai riferimento agli esempi di codice per scoprire come intrappolare il segnale SIGTERM
.
Chiusura forzata
Se uno o più container Cloud Run superano il limite di memoria totale del container, l'istanza viene terminata. Tutte le richieste ancora in fase di elaborazione sull'istanza
con un errore HTTP 500
.
Per offerte di lavoro
Per i job Cloud Run, le istanze di container vengono eseguite fino alla chiusura dell'istanza del container, fino al raggiungimento del timeout dell'attività o fino all'arresto anomalo del container.
Chiusura forzata
Viene terminata un'istanza di container Cloud Run che supera il limite di memoria consentito. Tutte le richieste ancora in 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'arresto effettivo, a quel punto Cloud Run invia un segnale SIGKILL
, arrestando l'istanza del container.
Durante questo periodo, alle istanze di container viene allocata la CPU per l'intero ciclo di vita e vengono fatturate.
Fai riferimento all'esempio di codice SIGTERM per scoprire come eseguire il trap del segnale SIGTERM
.
Risorse istanza container
CPU
A ogni container Cloud Run in un'istanza viene allocata per impostazione predefinita la vCPU configurata (1 per impostazione predefinita). È possibile configurare i limiti di CPU separatamente su ogni container.
Una vCPU viene implementata come un'astrazione dell'hardware sottostante per fornire il tempo di CPU equivalente approssimativo di un singolo hyperthread hardware su piattaforme CPU variabili. Tutte le piattaforme CPU utilizzate da Cloud Run supportano il set di istruzioni AVX2. Tieni presente che il contratto del container non contiene ulteriori dettagli 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 il ciclo di 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, anche queste saranno soggette alla configurazione dell'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 separatamente per ogni container.
Gli utilizzi tipici della memoria includono:
- Codice caricato in 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 come OpCache PHP
- Utilizzo memoria per richiesta
- Volumi in memoria condivisi
Contemporaneità (servizi)
Per i servizi Cloud Run, per impostazione predefinita ogni istanza 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 del container
Se utilizzi l'ambiente di esecuzione di prima generazione, i container Cloud Run vengono sottoposti a sandbox mediante la sandbox del runtime dei container gVisor. Come documentato nel riferimento sulla compatibilità delle chiamate di sistema di gVisor, alcune chiamate di sistema potrebbero non essere supportate da questa sandbox del container.
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 metadati istanza
Le istanze Cloud Run espongono un server di metadati che puoi utilizzare per recuperare i dettagli dei container, come ID progetto, regione, ID istanza o account di servizio. Puoi utilizzare il server di metadati anche 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 la sezione Recupero dei metadati.
Nella tabella seguente sono elencate alcune delle informazioni sul server dei metadati disponibili:
Percorso | Descrizione |
---|---|
/computeMetadata/v1/project/project-id |
ID 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 |
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 in formato 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 dei file che utilizzi nei container devono essere compatibili con UTF-8, ovvero UTF-8 o UTF-8 convertibile in sicurezza automaticamente in UTF-8. Se i nomi dei file utilizzano codifiche diverse, esegui la build Docker 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 dei container non riesce se i nomi 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, si verifica un timeout dopo 10 minuti di tempo di inattività per le richieste dal container a VPC. Per le richieste dal container a internet, si verifica un timeout dopo 20 minuti di inattività.
Reimpostazione della connessione in uscita
I flussi di connessioni dal container sia a VPC sia a internet possono essere interrotti e sostituiti a volte al riavvio o all'aggiornamento dell'infrastruttura sottostante. Se l'applicazione riutilizza connessioni di lunga durata, ti consigliamo di configurarla in modo da ristabilire le connessioni per evitare il riutilizzo di una connessione inattiva.