1. Introduzione
Panoramica
Le funzioni di Cloud Run consentono di specificare le revisioni che devono ricevere il traffico e le percentuali di traffico ricevute da una revisione. Le revisioni ti consentono di eseguire il rollback a una revisione precedente, implementare gradualmente una revisione e suddividere il traffico tra più revisioni.
Questi codelab mostrano come utilizzare le revisioni per gestire il traffico alle funzioni di Cloud Run. Per scoprire di più sulle revisioni, consulta la documentazione di Cloud Run.
Cosa imparerai a fare
- Come suddividere il traffico tra due o più revisioni per una funzione Cloud Run
- Come implementare gradualmente una nuova revisione
- Come eseguire il rollback a una revisione precedente
2. Configurazione e requisiti
Prerequisiti
- Hai eseguito l'accesso alla console Cloud.
- Hai già eseguito il deployment di una funzione Cloud Run. Ad esempio, per iniziare, puoi seguire il deployment di una funzione Cloud Run.
Attiva Cloud Shell
- Dalla console Cloud, fai clic su Attiva Cloud Shell
.
Se è la prima volta che avvii Cloud Shell, ti verrà mostrata una schermata intermedia che descrive di cosa si tratta. Se ti è stata presentata una schermata intermedia, fai clic su Continua.
Il provisioning e la connessione a Cloud Shell dovrebbero richiedere solo qualche istante.
Questa macchina virtuale viene caricata con tutti gli strumenti di sviluppo necessari. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. Gran parte, se non tutto, del lavoro in questo codelab può essere svolto con un browser.
Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è già impostato sul tuo ID progetto.
- Esegui questo comando in Cloud Shell per verificare che l'account sia autenticato:
gcloud auth list
Output comando
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto:
gcloud config list project
Output comando
[core] project = <PROJECT_ID>
In caso contrario, puoi impostarlo con questo comando:
gcloud config set project <PROJECT_ID>
Output comando
Updated property [core/project].
3. Suddivisione del traffico
Questo esempio mostra come creare una funzione che legga una variabile di ambiente del colore e risponda con il nome della revisione utilizzando quel colore di sfondo.
Anche se questo codelab utilizza node.js, puoi usare qualsiasi runtime.
Impostare le variabili di ambiente
Puoi impostare le variabili di ambiente che verranno utilizzate durante questo codelab.
REGION=<YOUR_REGION> PROJECT_ID=<YOUR-PROJECT-ID> BG_COLOR=darkseagreen
crea la funzione
Per prima cosa, crea una directory per il codice sorgente ed esegui cd in quella directory.
mkdir revisions-gcf-codelab && cd $_
Quindi, crea un file package.json con i seguenti contenuti:
{
"dependencies": {
"@google-cloud/functions-framework": "^3.0.0"
}
}
A questo punto, crea un file di origine index.js con i seguenti contenuti:
const functions = require('@google-cloud/functions-framework');
const BG_COLOR = process.env.BG_COLOR;
const K_REVISION = process.env.K_REVISION;
functions.http('helloWorld', (req, res) => {
res.writeHead(200, { 'Content-Type': 'text/html' });
res.end('<html><body style="background-color:' + BG_COLOR + ';"' + '><div><p>' + 'Hello from ' + K_REVISION + ' using color ' + BG_COLOR + '</p></div></body>' + '</html>');
});
Per eseguire il deployment di una funzione Cloud Run direttamente in Cloud Run, esegui questo comando:
gcloud beta run deploy traffic-splitting-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--set-env-vars BG_COLOR=$BG_COLOR
Se preferisci eseguire il deployment come Cloud Functions (2a gen), utilizza il seguente comando:
gcloud functions deploy traffic-splitting-gcf \ --gen2 \ --runtime=nodejs20 \ --region=$REGION \ --source=. \ --entry-point=helloWorld \ --trigger-http \ --no-allow-unauthenticated \ --set-env-vars BG_COLOR=$BG_COLOR
Per testare la funzione, puoi eseguire il curl dell'endpoint esistente per vedere il colore verde mare scuro nell'html o utilizzare il browser per raggiungere direttamente l'endpoint e vedere il colore di sfondo.
SERVICE_URL=$(gcloud run services describe traffic-splitting-gcf --platform managed --region $REGION --format 'value(status.url)') curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
Ora esegui il deployment di una seconda revisione con un colore di sfondo marrone chiaro.
Per eseguire il deployment di una funzione Cloud Run direttamente su Cloud Run, esegui il seguente comando:
# update the env var
BG_COLOR=tan
gcloud beta run deploy traffic-splitting-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferisci eseguire il deployment come Cloud Functions (2a gen), utilizza il seguente comando:
# update the env var BG_COLOR=tan gcloud functions deploy traffic-splitting-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-allow-unauthenticated \ --update-env-vars BG_COLOR=$BG_COLOR
Ora, quando esegui curl dell'endpoint, vedrai il colore di sfondo marrone chiaro.
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
Suddividi il traffico 50-50
Per suddividere il traffico tra le revisioni verde acqua e marrone chiaro, devi trovare gli ID revisione dei servizi Cloud Run sottostanti. Per visualizzare gli ID revisione, esegui questo comando:
gcloud run revisions list --service traffic-splitting-gcf \ --region $REGION --format 'value(REVISION)'
Dovresti vedere risultati simili a quelli riportati di seguito
traffic-splitting-gcf-00003-qoq traffic-splitting-gcf-00002-zag
Puoi suddividere il traffico 50/50 tra le due revisioni eseguendo questo comando:
gcloud run services update-traffic traffic-splitting-gcf \ --region $REGION \ --to-revisions <REVISION1>=50,<REVISION2>=50
Testa la suddivisione del traffico
Puoi testare la funzione visitando il relativo URL pubblico (tramite curl o direttamente nel browser).
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL
La metà delle volte dovresti vedere la revisione verde mare scuro e l'altra metà la revisione marrone chiaro. Nell'output vedrai anche il nome della revisione, ad esempio
<html><body style="background-color:tan;"><div><p>Hello traffic-splitting-gcf-00006-qoq</p></div></body></html>
4. Implementazioni graduali
In questa sezione imparerai a implementare gradualmente le modifiche a una nuova revisione di Cloud Functions. Puoi scoprire di più sulle implementazioni graduali nella documentazione.
Utilizzerai lo stesso codice della sezione precedente, ma eseguirai il deployment come nuova funzione Cloud Functions.
Innanzitutto, imposta il colore di sfondo su beige ed esegui il deployment della funzione con il nome gradual-rollouts-gcf.
Per eseguire il deployment di una funzione Cloud Run direttamente in Cloud Run, esegui questo comando:
# update the env var
BG_COLOR=beige
gcloud beta run deploy gradual-rollouts-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferisci eseguire il deployment come Cloud Functions (2a gen), utilizza il seguente comando:
# update the env var BG_COLOR=beige # deploy the function gcloud functions deploy gradual-rollouts-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-allow-unauthenticated \ --update-env-vars BG_COLOR=$BG_COLOR
Supponiamo di voler implementare gradualmente una nuova revisione con il colore di sfondo lavanda.
Innanzitutto, imposta il beige della revisione corrente in modo che riceva il 100% del traffico. In questo modo, i futuri deployment della funzione Cloud Functions non riceveranno traffico. Per impostazione predefinita, Cloud Functions imposta il 100% del traffico sulla revisione con il flag latest. Se specifichi manualmente che questa revisione attuale beige deve ricevere tutto il traffico, la revisione con il flag latest non riceverà più il 100% del traffico. Consulta la documentazione.
# get the revision name BEIGE_REVISION=$(gcloud run revisions list --service gradual-rollouts-gcf \ --region $REGION --format 'value(REVISION)') # now set 100% traffic to that revision gcloud run services update-traffic gradual-rollouts-gcf --to-revisions=$BEIGE_REVISION=100 --region $REGION
Vedrai un output simile a Traffic: 100% gradual-rollouts-gcf2-00001-yox
Ora puoi eseguire il deployment di una nuova revisione che non riceverà traffico. Anziché apportare modifiche al codice, puoi aggiornare la variabile di ambiente BG_COLOR per questa revisione.
Per eseguire il deployment di una funzione Cloud Run direttamente su Cloud Run, esegui questo comando:
# update color
BG_COLOR=lavender
# deploy the function that will not receive any traffic
gcloud beta run deploy gradual-rollouts-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferisci eseguire il deployment come Cloud Functions 2ª gen., utilizza il seguente comando:
# update color BG_COLOR=lavender # deploy the function that will not receive any traffic gcloud functions deploy gradual-rollouts-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-allow-unauthenticated \ --update-env-vars BG_COLOR=$BG_COLOR \ --tag $BG_COLOR
Ora aggiorna la variabile di ambiente SERVICE_URL per utilizzare la funzione gradual-rollouts-gcf
SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')
e ora quando esegui curl del servizio
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
vedrai il colore beige, anche se la revisione di cui è stato eseguito il deployment più di recente è il lavanda.
<html><body style="background-color:beige;"><div><p>Hello from gradual-rollouts-gcf-24jan16-staging-2-00001-kop using color beige</p></div></body></html>
Testa una revisione che gestisce il traffico dello 0%
Supponi di aver verificato che il deployment della revisione sia andato a buon fine e che stia gestendo il traffico dello 0%. Anche se ha superato i controlli di integrità, vuoi comunque verificare che questa revisione utilizzi il colore di sfondo lavanda.
Per testare la revisione del lavanda, puoi applicare un tag a quella revisione. Il tagging ti consente di testare direttamente la nuova revisione in un URL specifico, senza gestire traffico.
Innanzitutto, ottieni l'URL dell'immagine per quella revisione.
IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')
Ora tagga l'immagine con il colore associato.
gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated
Verrà visualizzato un output simile al seguente:
The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app
Ora puoi eseguire il comando curl direttamente
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>
e guarda il colore lavanda nei risultati:
<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>
Aumento graduale del traffico
Ora puoi iniziare a inviare traffico alla revisione del colore lavanda. L'esempio seguente mostra come inviare l'1% del traffico a lavanda.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=1
Per inviare il 50% del traffico a lavanda, puoi utilizzare lo stesso comando, ma specificare il 50%.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=50
Dovresti vedere un elenco del volume di traffico ricevuto da ogni revisione.
Traffic:
50% gradual-rollouts-gcf-00001-hos
50% gradual-rollouts-gcf-00004-mum
lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.a.run.app
Quando vuoi stendere completamente la lavanda, puoi impostare la lavanda al 100% per sostituire il beige.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100
e ora, quando visiti o raccogli l'URL del servizio della funzione gradual-rollouts-gcf,
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
vedrai solo lavanda.
<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>
5. Rollback
Supponiamo che sia arrivato un primo feedback UX, che indica che i clienti preferiscono il beige al lavanda e che tu debba tornare al beige.
Puoi eseguire il rollback alla revisione precedente (beige) eseguendo questo comando.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100
e ora, quando curl o visiti l'endpoint dell'URL della funzione,
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
verrà visualizzato il colore beige.
<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>
Puoi scoprire di più sui rollback nella documentazione.
6. Complimenti!
Complimenti per aver completato il codelab.
Consigliamo di esaminare la documentazione su implementazioni, rollback e migrazione del traffico
Argomenti trattati
- Come suddividere il traffico tra due o più revisioni per una funzione Cloud Run
- Come implementare gradualmente una nuova revisione
- Come eseguire il rollback a una revisione precedente
7. Esegui la pulizia
Per evitare addebiti involontari, ad esempio se questa funzione Cloud Run viene richiamata inavvertitamente più volte rispetto all'allocazione mensile dell'invocazione della funzione Cloud Functions nel livello senza costi, puoi eliminare la funzione Cloud Run o eliminare il progetto che hai creato nel passaggio 2.
Per eliminare una funzione Cloud Run di cui è stato eseguito il deployment in Cloud Run, vai a Cloud Run nella console Cloud all'indirizzo https://console.cloud.google.com/functions/ ed elimina le funzioni che hai creato in questo codelab.
Per eliminare le funzioni Cloud Run di cui è stato eseguito il deployment come funzioni di 2a generazione, vai a Cloud Functions nella console Cloud all'indirizzo https://console.cloud.google.com/functions/ ed elimina le funzioni che hai creato in questo codelab.
Se scegli di eliminare l'intero progetto, puoi andare all'indirizzo https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto che hai creato nel passaggio 2 e scegliere Elimina. Se elimini il progetto, dovrai modificare i progetti nel tuo Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.