Rollbacks, gradual rollouts, and traffic migration

Cloud Run lets you specify which revisions should receive traffic and to specify traffic percentages that are received by a revision. This feature lets you rollback to a previous revision, gradually deploy a revision, and split traffic between multiple revisions. This page describes how to use this feature to manage traffic to your Cloud Run revisions.

Note that traffic routing adjustments are not instantaneous. When you change traffic for revisions, all requests being processed will continue to completion. In flight requests won't be dropped and may be directed to either a new revision or a previous revision during the transition period.

Traffic splitting and session affinity

If you are splitting traffic between multiple revisions with session affinity enabled, see Session affinity and traffic splitting for details on the effect of session affinity on traffic splitting.

Lifecycle of traffic splits

If you split traffic between multiple revisions or assigned traffic to a previous revision, all subsequent deployments use that traffic split pattern going forward. To return to just using the latest revision without traffic splitting, send all traffic to the latest revision.

Required roles

To get the permissions that you need to manage Cloud Run services and revisions, ask your administrator to grant you the following IAM roles:

If you are managing a service that was deployed from a container image:
- Cloud Run Developer (roles/run.developer) on the Cloud Run service
- Service Account User (roles/iam.serviceAccountUser) on the service identity
- Artifact Registry Reader (roles/artifactregistry.reader) on the Artifact Registry repository of the container images of the service (if applicable)
If you are managing a service that was deployed from source code:
- Cloud Run Source Developer (roles/run.sourceDeveloper) on your project
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on your project
- Service Account User (roles/iam.serviceAccountUser) on the service identity
- Additionally, grant the Cloud Run Builder (roles/run.builder) role to the Cloud Build service account on the project. The build service account is responsible for building your service, and defaults to the Compute Engine default service account.

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Roll back to a previous revision

To roll back to a previous revision:

Console

In the Google Cloud console, go to the Cloud Run Services page:

Go to Cloud Run
Locate the service in the services list, and click it.
Click the Revision history tab to show the list of current revisions for that service.
In the list of revisions, click the ellipsis icon to the right of the revision you are rolling back:
Click Manage traffic to display the manage traffic options.
Select Send all traffic to one revision and select the revision from the drop-down.
Click Save.

gcloud

Use the following command:

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

Replace SERVICE with the name of the service.
Replace REVISION with the name of the revision you are rolling back to.

YAML

If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
```
gcloud run services describe SERVICE --format export > service.yaml
```

Below the spec attribute, locate and update the traffic attribute to the following:

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

Replace

REVISION with the name of the revision you are rolling back to.

Replace the service with its new configuration using the following command:
```
gcloud run services replace service.yaml
```
Wait for the update to complete: you should see a message that the revision you are rolling back from has been deployed and is serving 0 percent of traffic.

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Add the following to a google_cloud_run_v2_service resource in your Terraform configuration:

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"

  }
}

Gradual roll out for revisions

To roll out a new revision gradually:

Console

In the Google Cloud console, go to the Cloud Run Services page:

Go to Cloud Run
Select a service in the services list.
Configure your service as needed.
Click View diff and redeploy.
Make sure that Serve this revision immediately is not selected.
Click Deploy changes.
Click the Revision history tab. If the new revision is not listed yet, click the refresh button.
In the list of revisions, click the ellipsis icon to the right of the revision you are rolling out to.
Click Manage traffic to display the manage traffic options.
Click Split traffic across multiple revisions.
Select the revisions you want to split traffic between and the percentage of traffic for each revision.
Click Save.

gcloud

To deploy a service from a container image:

Deploy the revision you want to roll out gradually, initially setting it to receive no traffic:
- To deploy a service from source code:
```
gcloud run deploy --image IMAGE --no-traffic
```
  Replace IMAGE with the image you are deploying.
- To deploy a service from source code:
```
gcloud run deploy SERVICE --source . --no-traffic
```
  Replace SERVICE with the name of your service.
Specify the percentage of traffic you want the new revision to handle, for example, 5 percent:
```
gcloud run services update-traffic SERVICE --to-revisions REVISION=PERCENTAGE
```
- Replace SERVICE with the name of the service.
- Replace REVISION with the name of the revision you are rolling out gradually. To specify the latest revision, you can use LATEST, for example, LATEST=5.
- Replace PERCENTAGE with the percentage of traffic you want to send to the new revision, for example, 5 to send it 5% of traffic.
After the revision's performance is satisfactory, repeat the preceding update-traffic step, but increase the percentage value as desired.

YAML

If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
```
gcloud run services describe SERVICE --format export > service.yaml
```

Make any desired configuration changes to the service, and specify the revision name you want for the new revision:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
 template:
   metadata:
     annotations:
     ...
     name: REVISION-NAME

Replace

REVISION-NAME with the name you want the new revision to have.

Below the spec attribute, locate and update the traffic attribute so that the new revision serves only a small amount of traffic:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-NEW
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER
```
Note that the percentages must add up to 100. Replace
- REVISION-NEW with the name of the revision you are rolling out gradually.
- REVISION-FORMER with the name of the serving revision.
- PERCENT-NEW with the traffic percentage you want to send to the new revision, for example use 10 to send 10% of the traffic to that revision.
- PERCENT-FORMER with the traffic percentage you want to send to the old revision
Wait for the update to complete: you should see a message that the new revision you are gradually rolling out has been deployed and is serving the traffic percentage value you used.

Terraform

Add the following to your .tf file and gradually update the traffic percentage from previous revision to the latest revision. Keep in mind that every traffic change will require another terraform apply to be executed.

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

Apply the changes by entering terraform apply.

Split traffic between multiple revisions

To split traffic between two or more revisions:

Console

In the Google Cloud console, go to the Cloud Run Services page:

Go to Cloud Run
Locate the service in the services list, and click it.
Click the Revision history tab.
Click Manage traffic.
The currently serving new revision is listed. In the form:
1. Set the currently serving revision percentage to the chosen split.
2. Select one of the previous revisions using the list and set it to the chosen percentage split.
3. To split traffic between more revisions, click Add Revision, select the revision, and set the percentage to the chosen split.
4. Click Save.

gcloud

Specify the revisions and the percentage of traffic for each revision in a comma delimited list:

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

Replace SERVICE with the name of the service.
Replace LIST with a comma delimited list of revisions and percentages:
REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx
for example, hello2-00005-red=25,hello2-00001-bod=25,hello2-00002-nan=50.

YAML

If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Below the spec attribute, locate and update the traffic attribute so that the new revision serves only a small amount of traffic:
```
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
```
Note that percentages must add up to 100. Replace
- REVISION-A, REVISION-B, REVISION-C with the revisions you are allotting traffic to.
- PERCENT-A, PERCENT-B, PERCENT-C with the percentage for the corresponding revision.
Replace the service with its new configuration using the following command:
```
gcloud run services replace service.yaml
```
Wait for the update to complete: you should see a message that the new revision you are gradually rolling out has been deployed and is serving 5 percent (or whatever gradual value you used) of traffic.

Terraform

Add the following to your Terraform file:

resource "google_cloud_run_v2_service"

Rollbacks, gradual rollouts, and traffic migration Stay organized with collections Save and categorize content based on your preferences.

Traffic splitting and session affinity

Lifecycle of traffic splits

Required roles

Roll back to a previous revision

Console

gcloud

YAML

Terraform

Gradual roll out for revisions

Console

gcloud

YAML

Terraform

Split traffic between multiple revisions

Console

gcloud

YAML

Terraform

Rollbacks, gradual rollouts, and traffic migration