Utilizzo delle revisioni nelle funzioni di Cloud Run per la suddivisione del traffico, le implementazioni graduali e i rollback

1. Introduzione

Panoramica

Cloud Run Functions ti consente 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 dividere il traffico tra più revisioni.

Questo codelab mostra come utilizzare le revisioni per gestire il traffico verso le funzioni Cloud Run. Per saperne di più sulle revisioni, consulta la documentazione di Cloud Run.

Cosa imparerai a fare

• Come dividere 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 a Cloud Console.
• 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

1. Nella console Cloud, fai clic su Attiva Cloud Shell .

Se è la prima volta che avvii Cloud Shell, viene visualizzata una schermata intermedia che ne descrive le funzionalità. Se è stata visualizzata una schermata intermedia, fai clic su Continua.

Bastano 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 del lavoro per questo codelab, se non tutto, può essere svolto con un browser.

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è autenticato e il progetto è impostato sul tuo ID progetto.

2. 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`

Nota:lo strumento a riga di comando gcloud è il potente strumento a riga di comando unificato di Google Cloud. È già installato in Cloud Shell. Noterai il supporto del completamento automatico. Potrebbe esserti chiesto di autenticarti la prima volta che esegui un comando. Per saperne di più, consulta la panoramica dello strumento a riga di comando gcloud.

3. Esegui questo 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].

Nota:se completi questo tutorial al di fuori di Cloud Shell, segui la procedura per configurare le credenziali predefinite dell'applicazione.

3. Suddivisione del traffico

Questo esempio mostra come creare una funzione che legge una variabile di ambiente di colore e risponde con il nome della revisione utilizzando quel colore di sfondo.

Sebbene questo codelab utilizzi Node.js, puoi utilizzare qualsiasi runtime.

Imposta le variabili di ambiente

Puoi impostare le variabili di ambiente che verranno utilizzate in questo codelab.

REGION=<YOUR_REGION>
PROJECT_ID=<YOUR-PROJECT-ID>
BG_COLOR=darkseagreen

Crea la funzione

Innanzitutto, crea una directory per il codice sorgente e accedi tramite cd.

mkdir revisions-gcf-codelab && cd $_

Quindi, crea un file package.json con il seguente contenuto:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

Successivamente, crea un file di origine index.js con il seguente contenuto:

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 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 (2nd 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 comando curl sull'endpoint esistente per visualizzare il colore verde mare 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 questo 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 (2nd 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 dividere il traffico tra le revisioni verde scuro e marrone chiaro, devi trovare gli ID revisione dei servizi Cloud Run sottostanti. Puoi visualizzare gli ID revisione eseguendo questo comando:

gcloud run revisions list --service traffic-splitting-gcf \
  --region $REGION --format 'value(REVISION)'

Dovresti visualizzare 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 suo URL pubblico (tramite curl o direttamente nel browser).

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL

Metà delle volte dovresti vedere la revisione verde mare scuro e l'altra metà la revisione marrone chiaro. Vedrai anche il nome della revisione elencato nell'output, 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ù sui rollout graduali nella documentazione.

Utilizzerai lo stesso codice della sezione precedente, ma lo eseguirai il deployment 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 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 (2nd 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 deployment di Cloud Functions non riceveranno traffico. Per impostazione predefinita, Cloud Functions imposta il traffico al 100% 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 (2nd 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 distribuita più di recente è quella 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 gestisce lo 0% del traffico

Supponiamo che tu abbia verificato che la revisione è stata implementata correttamente e che gestisce lo 0% del 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 alla revisione. Il tagging ti consente di testare direttamente la nuova revisione a un URL specifico, senza attivare il traffico.

Innanzitutto, recupera l'URL dell'immagine per la 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 il comando curl di questa revisione direttamente

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>

e visualizza 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 lavender.

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 visualizzare 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 il lancio completo di lavanda, puoi impostare il colore 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 esegui il comando curl sull'URL del servizio della funzione gradual-rollouts-gcf,

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

vedrai solo il colore lavanda.

<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>

5. Rollback

Supponiamo che siano arrivati i primi feedback sull'esperienza utente, che indicano che i clienti preferiscono il beige al 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

e ora, quando esegui curl o visiti l'endpoint URL della funzione,

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

vedrai il colore beige.

<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>

Per saperne di più sui rollback, consulta la documentazione.

6. Complimenti!

Congratulazioni per aver completato il codelab.

Ti consigliamo di consultare la documentazione su implementazioni, rollback e migrazione del traffico.

Argomenti trattati

• Come dividere 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 di chiamate di Cloud Functions nel livello senza costi), puoi eliminare la funzione Cloud Run o 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 seconda 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 alla pagina 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 cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.