Rollbacks, déploiements progressifs et migration du trafic

Cloud Run vous permet d'indiquer les révisions qui doivent recevoir du trafic et de spécifier les pourcentages de trafic reçus par une révision. Cette fonctionnalité vous permet 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. Cette page explique comment gérer le trafic vers vos révisions Cloud Run à l'aide de cette fonctionnalité.

Notez que les ajustements de routage du trafic ne sont pas instantanés. Lorsque vous modifiez le trafic associé aux révisions, toutes les requêtes en cours de traitement continuent leur exécution jusqu'à la fin. Les requêtes en cours ne sont pas supprimées et peuvent être dirigées vers une nouvelle révision ou vers une révision précédente pendant la période de transition.

Si vous répartissez le trafic entre plusieurs révisions avec l'affinité de session activée, consultez la section Affinité de session et répartition du trafic pour en savoir plus sur l'effet de l'affinité de session sur la répartition du trafic.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les services et les révisions Cloud Run, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Développeur Cloud Run (roles/run.developer) sur votre service Cloud Run
Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service

Pour obtenir la liste des rôles et des autorisations IAM associés à Cloud Run, consultez les sections Rôles IAM Cloud Run et Autorisations IAM Cloud Run. Si votre service Cloud Run communique avec les API Google Cloud, telles que les bibliothèques clientes Cloud, consultez le guide de configuration de l'identité du service. Pour en savoir plus sur l'attribution de rôles, consultez les sections Autorisations de déploiement et Gérer les accès.

Effectuer un rollback vers une révision antérieure

Pour effectuer un rollback vers une version précédente :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Localisez le service dans la liste des services, puis cliquez dessus.
Cliquez sur l'onglet Revisions (Révisions) afin d'afficher la liste des révisions en cours pour ce service.
Dans la liste des révisions, cliquez sur l'icône représentant trois points à droite de la révision pour laquelle vous effectuez le rollback :
Cliquez sur Manage Traffic (Gérer le trafic) pour afficher le formulaire de gestion du trafic :
1. Dans la liste déroulante, sélectionnez la révision précédente vers laquelle vous souhaitez effectuer le rollback.
2. Définissez le pourcentage de trafic de la révision précédente sur 100.
3. Définissez le pourcentage de la révision actuellement diffusée sur 0.
4. Cliquez sur Enregistrer.

gcloud

Exécutez la commande suivante :

gcloud run services update-traffic SERVICE --to-revisions REVISION=100

Remplacez SERVICE par le nom du service.
Remplacez REVISION par le nom de la révision vers laquelle vous effectuez le rollback.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Sous l'attribut spec, localisez et mettez à jour l'attribut traffic comme suit :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    percent: 100
```
Remplacer
- REVISION par le nom de la révision vers laquelle vous effectuez le rollback.
Remplacez la configuration du service en utilisant la commande suivante :
```
gcloud run services replace service.yaml
```
Attendez la fin de la mise à jour. Vous devriez voir un message indiquant que la révision à partir de laquelle vous effectuez le rollback a été déployée et diffuse 0 % du trafic.

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.

Ajoutez le code ci-dessous à votre fichier .tf :

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"

  }
}

Effectuer un déploiement progressif des révisions

Pour déployer progressivement une nouvelle révision :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Sélectionnez votre service dans la liste des services.
Cliquez sur Déployer une nouvelle révision.
Remplissez le formulaire de déploiement selon vos besoins, mais assurez-vous que la case Diffuser immédiatement la révision est DÉCOCHÉE.
Cliquez sur Déployer.
Cliquez sur Gérer le trafic.
La nouvelle révision est répertoriée, mais avec un pourcentage défini sur 0 : elle ne diffuse actuellement aucun trafic. Dans le formulaire :
1. Définissez le pourcentage souhaité pour cette révision, par exemple 5. Notez que le pourcentage de la version actuellement diffusée est automatiquement réduit de cette même valeur.
2. Cliquez sur Enregistrer.
3. Répétez les étapes permettant de gestion du trafic, mais avec les pourcentages modifiés, en augmentant la valeur selon les besoins de la nouvelle révision. Vous n'avez pas besoin d'effectuer un redéploiement pour modifier les pourcentages de trafic.

gcloud

Remarque : Si vous déployez une fonction lors de l'exécution de gcloud run deploy, vous devez utiliser gcloud beta run deploy, spécifier les indicateurs requis et disposer des rôles requis.

Déployez la révision que vous souhaitez déployer progressivement, en la définissant initialement de sorte qu'elle ne reçoive aucun trafic :
```
gcloud run deploy --image IMAGE --no-traffic
```
Remplacez IMAGE par l'image que vous déployez.
Spécifiez le pourcentage de trafic que la nouvelle révision doit gérer, par exemple 5 % :
```
gcloud run services update-traffic SERVICE --to-revisions REVISION=PERCENTAGE
```
- Remplacez SERVICE par le nom du service.
- Remplacez REVISION par le nom de la révision que vous déployez progressivement. Pour spécifier la dernière révision, vous pouvez utiliser LATEST, par exemple LATEST=5.
- Remplacez PERCENTAGE par le pourcentage de trafic que vous souhaitez envoyer à la nouvelle révision, par exemple 5 pour lui envoyer 5 % du trafic.
Une fois que les performances de la révision sont satisfaisantes, répétez l'étape update-traffic précédente, mais augmentez le pourcentage selon vos besoins.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Apportez toutes les modifications souhaitées à la configuration du service, puis spécifiez le nom que vous voulez attribuer à la nouvelle révision :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
 template:
   metadata:
     annotations:
     ...
     name: REVISION-NAME
```
Remplacer
- REVISION-NAME par le nom souhaité pour la révision.
Sous l'attribut spec, localisez et mettez à jour l'attribut traffic afin que la nouvelle révision ne diffuse qu'une faible quantité de trafic :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-NEW
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER
```
Notez que la somme des pourcentages doit être égale à 100. Remplacer
- REVISION-NEW par le nom de la révision soumise au déploiement progressif ;
- REVISION-FORMER par le nom de la révision assurant actuellement la diffusion ;
- PERCENT-NEW par le pourcentage de trafic que vous souhaitez envoyer à la nouvelle révision (par exemple, utilisez 10 pour envoyer 10 % du trafic vers cette révision) ;
- PERCENT-FORMER par le pourcentage de trafic que vous souhaitez envoyer à l'ancienne révision.
Attendez la fin de la mise à jour. Vous devriez voir un message indiquant que la nouvelle révision en cours de déploiement progressif a bien été déployée et diffuse le pourcentage du trafic que vous avez défini.

Terraform

Ajoutez les éléments suivants à votre fichier .tf et mettez progressivement à jour le pourcentage de trafic de la révision précédente vers la dernière révision. Gardez à l'esprit que chaque modification de trafic nécessitera l'exécution d'une autre commande terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {
    containers {
      # Image or image tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent = 0
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Appliquez les modifications en saisissant terraform apply.

Répartir le trafic entre plusieurs révisions

Pour répartir le trafic entre deux révisions ou plus :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Localisez le service dans la liste des services, puis cliquez dessus.
Cliquez sur Gérer le trafic.
La nouvelle révision actuellement diffusée s'affiche. Dans le formulaire :
1. Définissez le pourcentage de la révision actuellement diffusée sur la répartition souhaitée.
2. Sélectionnez l'une des révisions précédentes à l'aide de la liste déroulante, puis définissez-la sur le pourcentage de répartition souhaité.
3. Pour répartir le trafic entre plusieurs révisions, cliquez sur Ajouter une révision, sélectionnez la révision souhaitée, puis définissez le pourcentage sur la répartition souhaitée.
4. Cliquez sur Enregistrer.

gcloud

Spécifiez les révisions et le pourcentage de trafic pour chaque révision sous forme de liste, en les séparant par une virgule :

gcloud run services update-traffic SERVICE --to-revisions LIST

Remplacez SERVICE par le nom du service.
Remplacez LIST par une liste de révisions et de pourcentages séparés par une virgule :
REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx
par exemple hello2-00005-red=25,hello2-00001-bod=25,hello2-00002-nan=50.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Sous l'attribut spec, localisez et mettez à jour l'attribut traffic afin que la nouvelle révision ne diffuse qu'une faible quantité de trafic :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-A
    percent: PERCENT-A
  - revisionName: REVISION-B
    percent: PERCENT-B
  - revisionName: REVISION-C
    percent: PERCENT-C
```
Notez que la somme des pourcentages doit être égale à 100. Remplacer
- REVISION-A, REVISION-B, REVISION-C par les révisions auxquelles vous attribuez le trafic ;
- PERCENT-A, PERCENT-B, PERCENT-C par le pourcentage respectivement attribué à chaque révision.
Remplacez la configuration du service en utilisant la commande suivante :
```
gcloud run services replace service.yaml
```
Attendez la fin de la mise à jour. Vous devriez voir un message indiquant que la nouvelle révision en cours de déploiement progressif a bien été déployée et diffuse 5 % (ou la valeur progressive que vous avez définie) du trafic.

Terraform

Ajoutez le code ci-dessous à votre fichier .tf :

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "green"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent  = 25
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    percent = 75
    # This revision needs to already exist
    revision = "blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Appliquez les modifications en saisissant terraform apply.

Envoyer l'ensemble du trafic vers la dernière révision

Lorsque vous déployez une nouvelle révision, vous pouvez faire en sorte que celle-ci et toutes les révisions ultérieures diffusent 100 % du trafic dès que possible, ignorant ainsi toute répartition de trafic établie :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Localisez le service dans la liste des services, puis cliquez dessus.
Cliquez sur Déployer une nouvelle révision.
Remplissez le formulaire de déploiement selon vos besoins, en veillant à cocher la case intitulée Diffuser immédiatement la révision. Cette opération permet d'ignorer toute répartition du trafic existante, la nouvelle révision diffusant 100 % du trafic.
Cliquez sur Déployer.

gcloud

Pour envoyer l'ensemble du trafic vers la dernière révision déployée :

gcloud run services update-traffic SERVICE --to-latest

Remplacez SERVICE par le nom du service.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```

Sous l'attribut spec, localisez et mettez à jour l'attribut traffic comme suit :

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - latestRevision: true
    percent: 100

Remplacez la configuration du service en utilisant la commande suivante :
```
gcloud run services replace service.yaml
```
Attendez la fin de la mise à jour. Vous devriez voir un message indiquant que la (dernière) révision a bien été déployée et diffuse 100 % du trafic.

Terraform

Ajoutez le code ci-dessous à votre fichier .tf :

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  traffic {
    percent = 100
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Appliquez les modifications en saisissant terraform apply.

Utiliser des tags pour les tests, la migration du trafic et les rollbacks

Pour éviter que des frais ne vous soient facturés pour les révisions taguées, utilisez un nombre minimal d'instances au niveau du service ou supprimez des tags liés aux révisions lorsque vous n'en avez plus besoin.

Cette fonctionnalité est souvent utilisée pour tester et vérifier une nouvelle révision de service avant qu'elle diffuse du trafic, selon l'ordre suivant :

Exécution des tests d'intégration sur un conteneur pendant le développement
Déploiement du conteneur dans un projet Google Cloud que vous n'utilisez qu'à des fins de préproduction, sans diffuser de trafic, et tests sur une révision taguée
Déploiement en production, sans diffuser de trafic, et tests sur une révision taguée en production
Migration du trafic vers la révision taguée

Déployer une nouvelle révision taguée

Pour déployer une nouvelle révision d'un service existant en production, procédez comme suit :

gcloud

Déployer une nouvelle révision taguée :

gcloud run deploy myservice --image IMAGE_URL  --no-traffic --tag TAG_NAME

Remplacer

IMAGE_URL par l'URL de votre image ;
TAG_NAME par le nom de votre tag en minuscules.

Le tag vous permet de tester directement la nouvelle révision sur une URL spécifique, sans diffuser le trafic. L'URL commence par le nom du tag que vous avez fourni. Par exemple, si vous avez utilisé le nom de tag green sur le service myservice, vous devez tester la révision taguée sur l'URL https://green---myservice-abcdef.a.run.app.

Terraform

Ajoutez les éléments suivants à votre fichier .tf et mettez progressivement à jour le pourcentage de trafic de l'ancienne révision vers la plus récente avec le nouveau tag. Gardez à l'esprit que chaque modification de trafic nécessitera l'exécution d'une autre commande terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # image or tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "blue"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent  = 0
    revision = "blue"
    tag      = "tag-name"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Appliquez les modifications en saisissant terraform apply.

Supprimer un tag

Pour supprimer un tag d'une révision :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Sélectionnez votre service dans la liste des services.
Accédez à la section Révisions du service souhaité et sélectionnez la révision pour laquelle vous souhaitez supprimer le tag existant.
Passez la souris sur la colonne URL de révision (tags) et cliquez sur l'icône en forme de crayon, comme illustré ci-dessous.
Dans le menu contextuel URL de révision, cliquez sur l'icône Poubelle pour supprimer le tag actuel utilisé dans votre révision.
Cliquez sur Enregistrer.

gcloud

Pour supprimer un tag de révision :

gcloud run services update-traffic SERVICE --remove-tags TAG_NAME

Remplacer

TAG_NAME par le nom du tag vers lequel vous migrez le trafic ;
SERVICE par le nom du service duquel vous supprimez le tag.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Apportez toutes les modifications souhaitées à la configuration du service.

Sous l'attribut spec, localisez et supprimez l'attribut tag pour la révision taguée :

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW

Remplacez la configuration du service en utilisant la commande suivante :
```
gcloud run services replace service.yaml
```

Terraform

Ajoutez le code ci-dessous à votre fichier .tf :

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # No tags for this revision
    # Keep revision at 0% traffic
    percent = 0
    # This revision needs to already exist
    revision = "blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Appliquez les modifications en saisissant terraform apply.

Migrer le trafic vers une révision taguée

Après avoir vérifié que la nouvelle révision fonctionne correctement, vous pouvez commencer à migrer le trafic vers celle-ci à l'aide de la console Google Cloud, de la ligne de commande gcloud, Terraform ou d'un fichier YAML :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Localisez le service dans la liste des services, puis cliquez dessus :
Sélectionnez la révision taguée à laquelle vous souhaitez envoyer du trafic :
Cliquez sur Gérer le trafic.
Recherchez le nom de la révision taguée. Elle est répertoriée, mais avec un pourcentage défini sur 0 : elle ne diffuse actuellement pas de trafic. Dans le formulaire Gérer le trafic* :
1. Définissez le pourcentage souhaité pour cette révision, par exemple 5. Notez que le pourcentage de la version actuellement diffusée est automatiquement réduit de cette même valeur.
2. Cliquez sur Enregistrer.
3. Pendant plusieurs heures, ou plusieurs jours si cela est nécessaire, répétez les étapes de gestion du trafic en augmentant graduellement le pourcentage attribué à la révision taguée. Vous n'avez pas besoin d'effectuer un redéploiement pour modifier les pourcentages de trafic.

gcloud

Pour migrer le trafic vers un tag de révision spécifique, procédez comme suit :

gcloud run services update-traffic myservice --to-tags TAG_NAME=TRAFFIC_PERCENT

Remplacer

TAG_NAME par le nom du tag vers lequel vous migrez le trafic ;
TRAFFIC_PERCENT par le pourcentage de trafic que vous souhaitez diffuser via la révision taguée (par exemple, 1).

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Apportez toutes les modifications souhaitées à la configuration du service.
Sous l'attribut spec, localisez et mettez à jour l'attribut traffic de la révision taguée afin qu'elle ne diffuse qu'une faible quantité de trafic :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER
```
Notez que la somme des pourcentages doit être égale à 100. Remplacer
- REVISION par le nom de la révision taguée ;
- TAG_NAME par le nom du tag que vous déployez progressivement ;
- PERCENT-NEW par le pourcentage de trafic que vous souhaitez envoyer à la révision taguée (par exemple, utilisez 10 pour envoyer 10 % du trafic vers cette révision) ;
- REVISION-FORMER par le nom de la révision assurant actuellement la diffusion ;
- PERCENT-FORMER par le pourcentage de trafic que vous souhaitez envoyer à l'ancienne révision.
Remplacez la configuration du service en utilisant la commande suivante :
```
gcloud run services replace service.yaml
```
Attendez la fin de la mise à jour. Vous devriez voir un message indiquant que la nouvelle révision en cours de déploiement progressif a bien été déployée et diffuse le pourcentage du trafic que vous avez défini.

Terraform

Ajoutez le code ci-dessous à votre fichier .tf :

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    # Update revision to 50% traffic
    percent = 50
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Update tag to 50% traffic
    percent = 50
    # This tag needs to already exist
    tag = "tag-name"
  }
}

Pendant plusieurs heures, ou plusieurs jours si nécessaire, passez progressivement d'un tag à l'autre en augmentant le pourcentage selon les besoins pour la révision taguée.

Appliquez les modifications en saisissant terraform apply après chaque modification.

Étapes suivantes

Découvrez comment utiliser Cloud Deploy pour configurer un pipeline de livraison continue afin de déployer dans Cloud Run.