Utiliser des révisions dans les fonctions Cloud Run pour la répartition du trafic, les déploiements progressifs et les rollbacks

1. Introduction

Présentation

Les fonctions Cloud Run vous permettent d'indiquer les révisions censées recevoir du trafic et de spécifier les pourcentages de trafic reçus par une révision. Les révisions vous permettent d'effectuer un rollback vers une révision précédente, de déployer progressivement une révision et de répartir le trafic entre plusieurs révisions.

Ces ateliers de programmation vous expliquent comment utiliser les révisions pour gérer le trafic vers vos fonctions Cloud Run. Pour en savoir plus sur les révisions, consultez la documentation Cloud Run.

Points abordés

  • Comment répartir le trafic entre plusieurs révisions pour une fonction Cloud Run ?
  • Déployer progressivement une nouvelle révision
  • Effectuer un rollback vers une révision précédente

2. Préparation

Prérequis

  • Vous êtes connecté à la console Cloud.
  • Vous avez déjà déployé une fonction Cloud Run. Par exemple, vous pouvez suivre la procédure de déploiement d'une fonction Cloud Run pour commencer.

Activer Cloud Shell

  1. Dans Cloud Console, cliquez sur Activer Cloud Shell d1264ca30785e435.png.

cb81e7c8e34bc8d.png

Si vous démarrez Cloud Shell pour la première fois, un écran intermédiaire vous explique de quoi il s'agit. Si un écran intermédiaire vous s'est présenté, cliquez sur Continue (Continuer).

d95252b003979716.png

Le provisionnement et la connexion à Cloud Shell ne devraient pas prendre plus de quelques minutes.

7833d5e1c5d18f54.png

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute dans Google Cloud, ce qui améliore considérablement les performances du réseau et l'authentification. Vous pouvez réaliser une grande partie, voire la totalité, des activités de cet atelier de programmation dans un navigateur.

Une fois connecté à Cloud Shell, vous êtes en principe authentifié, et le projet est défini avec votre ID de projet.

  1. Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :
gcloud auth list

Résultat de la commande

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`
  1. Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet:
gcloud config list project

Résultat de la commande

[core]
project = <PROJECT_ID>

Si vous obtenez un résultat différent, exécutez cette commande :

gcloud config set project <PROJECT_ID>

Résultat de la commande

Updated property [core/project].

3. Répartition du trafic

Cet exemple montre comment créer une fonction qui lit une variable d'environnement de couleur et renvoie le nom de la révision avec cette couleur d'arrière-plan.

Bien que cet atelier de programmation utilise Node.js, vous pouvez utiliser n'importe quel environnement d'exécution.

Définir des variables d'environnement

Vous pouvez définir des variables d'environnement qui seront utilisées tout au long de cet atelier de programmation.

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

Créer la fonction

Commencez par créer un répertoire pour le code source et accédez-y avec la commande cd.

mkdir revisions-gcf-codelab && cd $_

Ensuite, créez un fichier package.json avec le contenu suivant:

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

Ensuite, créez un fichier source index.js avec le contenu suivant:

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>');
});

Pour déployer une fonction Cloud Run directement sur Cloud Run, exécutez la commande suivante :

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --set-env-vars BG_COLOR=$BG_COLOR

Si vous préférez déployer en tant que Cloud Functions (2e génération), utilisez la commande suivante :

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

Pour tester la fonction, vous pouvez utiliser curl pour accéder au point de terminaison existant afin de voir la couleur darkseagreen dans le code HTML, ou utiliser votre navigateur pour accéder directement au point de terminaison afin de voir la couleur d'arrière-plan.

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

Déployez maintenant une deuxième révision avec une couleur d'arrière-plan beige.

Pour déployer une fonction Cloud Run directement sur Cloud Run, exécutez la commande suivante:

# 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

Si vous préférez déployer en tant que Cloud Functions (2e génération), utilisez la commande suivante :

# 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

Lorsque vous appelez le point de terminaison avec curl, la couleur d'arrière-plan est maintenant beige.

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

Répartir le trafic de 50 à 50

Pour répartir le trafic entre les révisions Vert et tan, vous devez trouver les ID de révision des services Cloud Run sous-jacents. Vous pouvez afficher les ID de révision en exécutant la commande suivante :

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

Vous devriez obtenir des résultats semblables à ceux présentés ci-dessous.

traffic-splitting-gcf-00003-qoq
traffic-splitting-gcf-00002-zag

Vous pouvez répartir le trafic 50/50 entre les deux révisions en exécutant la commande suivante :

gcloud run services update-traffic traffic-splitting-gcf \
  --region $REGION \
  --to-revisions <REVISION1>=50,<REVISION2>=50

Tester la répartition du trafic

Vous pouvez tester la fonction en accédant à son URL publique (à l'aide de curl ou directement dans le navigateur).

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

La moitié du temps, vous devriez voir la version vert foncé et l'autre moitié, la version beige. Le nom de la révision s'affiche également dans la sortie, par exemple :

<html><body style="background-color:tan;"><div><p>Hello traffic-splitting-gcf-00006-qoq</p></div></body></html>

4. Déploiements progressifs

Dans cette section, vous allez apprendre à déployer progressivement les modifications vers une nouvelle révision de la fonction Cloud. Pour en savoir plus sur les déploiements progressifs, consultez la documentation.

Vous utiliserez le même code que dans la section précédente, mais vous le déploierez en tant que nouvelle fonction Cloud.

Tout d'abord, définissez la couleur d'arrière-plan sur beige et déployez la fonction nommée gradual-rollouts-gcf.

Pour déployer une fonction Cloud Run directement sur Cloud Run, exécutez la commande suivante :

# 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

Si vous préférez déployer en tant que Cloud Functions (2e génération), utilisez la commande suivante :

# 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

Supposons maintenant que nous souhaitions déployer progressivement une nouvelle version avec une couleur d'arrière-plan lavande.

Commençons par définir la révision actuelle (beige) pour qu'elle reçoive 100 % du trafic. Cela garantit que vos futurs déploiements de fonctions Cloud Functions ne recevront aucun trafic. Par défaut, Cloud Functions définit 100% du trafic vers la révision avec l'option latest. En spécifiant manuellement que cette révision beige actuelle doit recevoir tout le trafic, la révision avec l'indicateur latest ne recevra plus 100 % du trafic. Consultez la documentation.

# 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

Un résultat semblable à Traffic: 100% gradual-rollouts-gcf2-00001-yox s'affiche.

Vous pouvez maintenant déployer une nouvelle révision qui ne recevra aucun trafic. Au lieu d'apporter des modifications au code, vous pouvez mettre à jour la variable d'environnement BG_COLOR pour cette révision.

Pour déployer une fonction Cloud Run directement sur Cloud Run, exécutez la commande suivante:

# 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

Si vous préférez déployer en tant que Cloud Functions (2e génération), utilisez la commande suivante :

# 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

Mettez maintenant à jour la variable d'environnement SERVICE_URL pour qu'elle utilise la fonction gradual-rollouts-gcf

SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')

et maintenant, lorsque vous exécutez curl sur le service

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

La couleur beige s'affiche, même si la version lavande est la dernière à avoir été déployée.

<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>

Tester une révision diffusant 0% du trafic

Supposons que vous ayez vérifié que votre révision a bien été déployée et qu'elle diffuse 0% du trafic. Même si la révision a réussi les vérifications de l'état, vous devez toujours vérifier que cette révision utilise la couleur d'arrière-plan lavande.

Pour tester la version lavande, vous pouvez lui appliquer une balise. L'ajout de tags vous permet de tester directement la nouvelle révision sur une URL spécifique, sans diffuser de trafic.

Commencez par obtenir l'URL de l'image pour cette révision.

IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')

Taguez maintenant cette image avec la couleur qui lui est associée.

gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated

Vous devez obtenir un résultat semblable à ce qui suit :

The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app

Vous pouvez maintenant exécuter directement cette révision en curl

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

et la couleur lavande apparaît dans les résultats :

<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>

Augmenter progressivement le trafic

Vous pouvez maintenant commencer à envoyer du trafic vers la révision Lavande. L'exemple ci-dessous montre comment envoyer 1% du trafic vers la lavande.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=1

Pour envoyer 50% du trafic vers la lavande, vous pouvez utiliser la même commande, mais spécifier 50% à la place.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=50

Vous devriez voir une liste du volume de trafic reçu par chaque révision.

Traffic:
  50% gradual-rollouts-gcf-00001-hos
  50% gradual-rollouts-gcf-00004-mum
        lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.a.run.app

Lorsque vous êtes prêt à déployer complètement le lilas, vous pouvez le définir à 100 % pour remplacer le beige.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100

et maintenant, lorsque vous accédez à l'URL du service de fonction gradual-rollouts-gcf ou l'appelez avec curl,

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

vous ne verrez que de la lavande.

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

5. Rollbacks

Supposons que les premiers commentaires UX indiquent que les clients préfèrent le beige au lilas, et que vous devez revenir au beige.

Vous pouvez effectuer un rollback vers la révision précédente (beige) en exécutant cette commande.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100

Lorsque votre curl ou sur le point de terminaison de l'URL de la fonction

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

le mot beige sera renvoyé.

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

Pour en savoir plus sur les rollbacks, consultez la documentation.

6. Félicitations !

Félicitations, vous avez terminé cet atelier de programmation.

Nous vous recommandons de consulter la documentation sur les déploiements, les rollbacks et la migration du trafic.

Points abordés

  • Comment répartir le trafic entre plusieurs révisions pour une fonction Cloud Run ?
  • Déployer progressivement une nouvelle révision
  • Effectuer un rollback vers une version précédente

7. Effectuer un nettoyage

Pour éviter les frais involontaires (par exemple, si cette fonction Cloud Run est appelée par inadvertance plus de fois que votre quota mensuel d'appels de fonctions Cloud dans le niveau gratuit), vous pouvez supprimer la fonction Cloud Run ou le projet que vous avez créé à l'étape 2.

Pour supprimer une fonction Cloud Run déployée dans Cloud Run, accédez à Cloud Run dans la console Cloud à l'adresse https://console.cloud.google.com/functions/ et supprimez les fonctions que vous avez créées dans cet atelier de programmation.

Pour supprimer les fonctions Cloud Run déployées en tant que fonctions de deuxième génération, accédez à Cloud Functions dans la console Cloud à l'adresse https://console.cloud.google.com/functions/, puis supprimez les fonctions que vous avez créées dans cet atelier de programmation.

Si vous choisissez de supprimer l'intégralité du projet, vous pouvez accéder à https://console.cloud.google.com/cloud-resource-manager, sélectionner le projet que vous avez créé à l'étape 2, puis cliquer sur "Supprimer". Si vous supprimez le projet, vous devrez modifier les projets dans votre SDK Cloud. Vous pouvez afficher la liste de tous les projets disponibles en exécutant gcloud projects list.