1. Introduzione
Panoramica
Le funzioni Cloud Run ti consentono di specificare quali revisioni devono ricevere 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 verso le funzioni 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 la procedura per eseguire il deployment di una funzione Cloud Run.
Attiva Cloud Shell
- Nella console Cloud, fai clic su Attiva Cloud Shell
.
Se è la prima volta che avvii Cloud Shell, viene visualizzata una schermata intermedia che descrive di cosa si tratta. Se viene visualizzata una schermata intermedia, fai clic su Continua.
Dovrebbero bastare pochi istanti per eseguire il provisioning e connettersi a Cloud Shell.
Questa macchina virtuale è 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 e l'autenticazione della rete. 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 di colore e risponda con il nome della revisione utilizzando quel colore di sfondo.
Sebbene questo codelab utilizzi Node.js, puoi utilizzare 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"
}
}
Quindi, 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 su Cloud Run, esegui il seguente 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 2ª 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 curl dell'endpoint esistente per visualizzare il colore verde acqua scuro nel codice HTML oppure utilizzare il browser per accedere direttamente all'endpoint e visualizzare 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 2ª 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 il seguente 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 viene visualizzato 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. Per scoprire di più sui rollout graduali, consulta la documentazione.
Utilizzerai lo stesso codice della sezione precedente, ma lo eseguirai come nuova funzione Cloud.
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 su Cloud Run, esegui il seguente 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 2ª 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 ora di voler implementare gradualmente una nuova revisione con il colore di sfondo lavanda.
Innanzitutto, impostiamo la revisione corrente beige in modo che riceva il 100% del traffico. In questo modo, i futuri implementazioni di Funzioni Cloud 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 implementare 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 il seguente 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 era 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>
Testare una revisione che genera lo 0% di traffico
Supponiamo che tu abbia verificato che il deployment della revisione sia andato a buon fine e che non generi traffico. Anche se ha superato i controlli di integrità, vuoi comunque verificare che questa revisione utilizzi il colore di sfondo lavanda.
Per testare la revisione lavanda, puoi applicare un tag a quella revisione. I tag ti consentono di testare direttamente la nuova revisione in un URL specifico, senza pubblicare traffico.
Innanzitutto, ottieni l'URL immagine della 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
Vedrai 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 direttamente il curl di questa revisione
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>
e vedrai 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 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 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 è tutto pronto per implementare completamente il colore lavanda, puoi impostarlo al 100% per sostituire il beige.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100
Ora, quando visiti o esegui curl dell'URL del servizio della funzione gradual-rollouts-gcf,
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
Vedrai solo il lilla.
<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>
5. Rollback
Supponiamo che siano stati ricevuti feedback iniziali sull'esperienza utente che indicano che i clienti preferiscono il beige alla lavanda e che tu debba eseguire il rollback 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
Ora, quando esegui curl o visiti l'endpoint 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>
Per scoprire di più sui rollback, consulta la documentazione.
6. Complimenti!
Complimenti per aver completato il codelab.
Ti consigliamo di consultare 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 invocata inavvertitamente più volte rispetto alla allocazione mensile di invocazioni di Cloud Functions nel livello senza costi, puoi eliminare la funzione Cloud Run o il progetto 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 2ª gen., 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 alla pagina https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto 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.