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

• Répartir le trafic entre deux révisions ou plus 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 le tutoriel sur le déploiement d'une fonction Cloud Run pour commencer.

Activer Cloud Shell

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

Si vous démarrez Cloud Shell pour la première fois, un écran intermédiaire s'affiche pour vous expliquer de quoi il s'agit. Si cet écran s'est affiché, cliquez sur Continuer.

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

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 sur Google Cloud, ce qui améliore nettement 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.

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

Remarque : gcloud est l'outil de ligne de commande performant et unifié de Google Cloud. Il est préinstallé dans Cloud Shell. Il est également compatible avec la saisie semi-automatique via la touche de tabulation. Vous serez peut-être invité à vous authentifier la première fois que vous exécuterez une commande. Pour en savoir plus, consultez la présentation de l'outil de ligne de commande gcloud.

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

Remarque : Si vous suivez ce tutoriel en dehors de Cloud Shell, suivez Configurer les identifiants par défaut de l'application.

3. Répartition du trafic

Cet exemple vous montre comment créer une fonction qui lit une variable d'environnement de couleur et répond avec le nom de la révision en utilisant 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.

mkdir revisions-gcf-codelab && cd $_

Créez ensuite un fichier package.json avec le contenu suivant :

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

Créez ensuite 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 la fonction 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 soit envoyer une requête curl au point de terminaison existant pour voir la couleur vert mer dans le code HTML, soit utiliser votre navigateur pour accéder directement au point de terminaison et 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 la fonction 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

Désormais, lorsque vous appelez le point de terminaison avec curl, vous voyez la couleur d'arrière-plan beige.

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

Répartir le trafic à 50/50

Pour répartir le trafic entre les révisions vert océan et beige, 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 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 (avec 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 révision vert mer foncé et l'autre moitié, la révision beige. Le nom de la révision s'affiche également dans le résultat, 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 des modifications dans une nouvelle révision de 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 avec le nom 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 la fonction 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 voulions déployer progressivement une nouvelle révision avec la 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 garantira que vos futurs déploiements Cloud Functions ne recevront aucun trafic. Par défaut, Cloud Functions attribue 100 % du trafic à la révision avec l'indicateur latest. En spécifiant manuellement que la révision beige actuelle doit recevoir tout le trafic, la révision avec le drapeau 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 désormais déployer une nouvelle révision qui ne recevra aucun trafic. Au lieu de modifier le 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 la fonction 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 à jour la variable d'environnement SERVICE_URL pour utiliser 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 envoyez une requête cURL au service,

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

La couleur beige s'affichera, même si la révision lavande a été déployée le plus récemment.

<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 qui ne diffuse aucun trafic

Supposons que vous ayez vérifié que votre révision a été déployée avec succès et qu'elle diffuse 0 % du trafic. Même si elle a réussi les vérifications de l'état, vous devez quand même vérifier que cette révision utilise la couleur de fond lavande.

Pour tester la révision lavande, vous pouvez appliquer un tag à cette révision. Le tag vous permet de tester directement la nouvelle révision sur une URL spécifique, sans diffuser le 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)')

Taggez ensuite cette image avec la couleur 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 récupérer cette révision directement

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

et voir la couleur lavande 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>

Augmentation progressive du 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 version lavande.

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

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

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

Vous devriez voir une liste indiquant le trafic généré 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 la couleur lavande, vous pouvez la définir sur 100 % pour remplacer le beige.

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

Désormais, lorsque vous accédez à l'URL du service de fonction gradual-rollouts-gcf ou que vous l'interrogez avec curl,

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

seule la couleur lavande s'affichera.

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

5. Rollbacks

Supposons que vous ayez reçu les premiers commentaires sur l'UX, indiquant que les clients préfèrent le beige au lavande, et que vous deviez revenir au beige.

Vous pouvez revenir à 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

Désormais, lorsque vous effectuez une requête curl ou accédez au point de terminaison de l'URL de la fonction,

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

La couleur beige s'affiche.

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

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

• Répartir le trafic entre deux révisions ou plus pour une fonction Cloud Run
• Déployer progressivement une nouvelle révision
• Effectuer un rollback vers une révision précédente

7. Effectuer un nettoyage

Pour éviter des frais involontaires (par exemple, si cette fonction Cloud Run est invoquée par inadvertance plus de fois que votre quota mensuel d'invocations de fonctions Cloud dans le niveau sans frais), 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 sur Cloud Run, accédez à Cloud Run 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.

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 choisir "Supprimer". Si vous supprimez le projet, vous devrez changer de projet dans votre SDK Cloud. Vous pouvez afficher la liste de tous les projets disponibles en exécutant gcloud projects list.