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:

• Cloud Run Developer (roles/run.developer) on your Cloud Run service
• Service Account User (roles/iam.serviceAccountUser) on the service identity

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

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Locate the service in the services list, and click it.

3. Click the Revisions tab to show the list of current revisions for that service.

4. In the list of revisions, click the ellipsis icon to the right of the revision you are rolling back:

   

5. Click Manage Traffic to display the manage traffic form:

   1. Select the previous revision you want to roll back to in the drop-down list.
   2. Set that previous revision's traffic percentage to 100.
   3. Set the currently serving revision's percentage to 0.
   4. 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

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

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

3. Replace the service with its new configuration using the following command:

   gcloud run services replace service.yaml

4. 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 your .tf file:

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"

  }
}

Note: If the revision doesn't exist, you will receive the error: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

Gradual roll out for revisions

To roll out a new revision gradually:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Select a service in the services list.

3. Click Deploy New Revision.

4. Fill out the deploy form as needed, but make sure the checkbox labelled Serve this revision immediately is UNCHECKED.

5. Click Deploy.

6. Click Manage Traffic.

7. The new revision is listed but with a 0 percentage set: it is currently not serving any traffic. In the form:

   1. Set it to the desired percentage, for example, 5. Note that the currently serving version's percentage is automatically reduced by that same amount.
   2. Click Save.
   3. Repeat these Manage Traffic steps but with changed percentages, increasing the percentage as needed for the new revision. You do not need to redeploy to change the traffic percentages.

gcloud

Note: If you are deploying a function when running gcloud run deploy, you must use gcloud beta run deploy, specify the required flags, and have the required roles granted to you.

1. Deploy the revision you want to roll out gradually, initially setting it to receive no traffic:

   gcloud run deploy --image IMAGE --no-traffic

   Replace IMAGE with the image you are deploying.

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

3. After the revision's performance is satisfactory, repeat the preceding update-traffic step, but increase the percentage value as desired.

YAML

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

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

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

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

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Locate the service in the services list, and click on it.

3. Click Manage Traffic.

4. The currently serving new revision is listed. In the form:

   1. Set the currently serving revision percentage to the desired split.
   2. Select one of the previous revisions using the dropdown list and set it to the desired percentage split.
   3. To split traffic between more revisions, click Add Revision, select the desired revision, and set the percentage to the desired 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

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

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

3. Replace the service with its new configuration using the following command:

   gcloud run services replace service.yaml

4. 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 .tf file:

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

Apply the changes by entering terraform apply.

Send all traffic to the latest revision

When you deploy a new revision, you can make this revision and all future ones serve 100% of the traffic as soon as possible, overriding any established traffic split:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Locate the service in the services list, and click it.

3. Click Deploy New Revision.

4. Fill out the deploy form as needed, making sure you check the checkbox labelled Serve this revision immediately. This will override any existing traffic splitting, with the new revision serving 100 percent of traffic.

5. Click Deploy.

gcloud

To send all traffic to the most recently deployed revision:

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

Replace SERVICE with the name of the service.

YAML

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

2. 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:
     - latestRevision: true
       percent: 100
   

3. Replace the service with its new configuration using the following command:

   gcloud run services replace service.yaml

4. Wait for the update to complete: you should see a message that the (latest) revision is deployed and is serving 100 percent of traffic.

Terraform

Add the following to your .tf file:

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

Apply the changes by entering terraform apply.

Use tags for testing, traffic migration and rollbacks

Important: If you have minimum instances configured at the service-level, traffic tags do not allocate minimum instances for tagged revisions. If you have minimum instances configured at the revision-level, traffic tags allocate minimum instances for tagged revisions.

To avoid incurring billing costs for tagged revisions, use service-level minimum instances or remove tags on revisions when you don't need them anymore.

A common use case for this feature is to use it for testing and vetting of a new service revision before it serves any traffic, in this typical sequence:

1. Run integration tests on a container during development.
2. Deploy the container to a Google Cloud project that you use only for staging, serving no traffic, and test against a tagged revision.
3. Deploy it to production, without serving traffic, and test against a tagged revision in production.
4. Migrate traffic to the tagged revision.

Deploy a new tagged revision

To deploy a new revision of an existing service to production:

gcloud

Note: If you are deploying a function when running gcloud run deploy, you must use gcloud beta run deploy, specify the required flags, and have the required roles granted to you.

Deploy a new tagged revision:

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

Replace

• IMAGE_URL with the URL for your image
• TAG_NAME with your lower-case tag name

The tag allows you to directly test the new revision at a specific URL, without serving traffic. The URL starts with the tag name you provided: for example if you used the tag name green on the service myservice, you would test the tagged revision at the URL https://green---myservice-abcdef.a.run.app

Terraform

Add the following to your .tf file and gradually update the traffic percentage from old revision to the newest revision with the new tag. 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" 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"
  }
}

Apply the changes by entering terraform apply.

Remove a tag

To remove a tag from a revision:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Select a service in the services list.

3. Navigate to the Revisions section within your desired service and select the revision for which you would like to remove the existing tag.

4. Hold the pointer over the Revision URLs (tags) column and click the pencil icon:

   

5. In the Revision URLs dialog menu, click the Bin icon to remove the current tag used in your revision.

6. Click Save.

gcloud

To remove a revision tag:

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

Replace

• TAG_NAME with the name of the tag you are migrating traffic to
• SERVICE with the name of the service you are removing the tag from

YAML

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

2. Make any desired configuration changes to the service.

3. Below the spec attribute, locate and remove the tag attribute for the tagged revision:

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

4. Replace the service with its new configuration using the following command:

   gcloud run services replace service.yaml

Terraform

Add the following to your .tf file:

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

Apply the changes by entering terraform apply.

Note: If the revision doesn't exist, you will receive the error: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

Migrating traffic to a tagged revision

After confirming that the new revision works properly, you can start migrating traffic to it using the Google Cloud console, the gcloud command line, Terraform, or a YAML file:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Locate the service in the services list, and click it:

3. Select the tagged revision you want to send traffic to:

   

4. Click Manage Traffic.

5. Locate the tagged revision name: it is listed but with a 0 percentage set: it is currently not serving any traffic. In the Manage traffic* form:

   1. Set it to the desired percentage, for example, 5. Note that the currently serving version's percentage is automatically reduced by that same amount.
   2. Click Save.
   3. Over a period of hours or days, as needed, repeat these Manage Traffic steps but with changed percentages, increasing the percentage as needed for the tagged revision. You do not need to redeploy to change the traffic percentages.

gcloud

To migrate traffic to a specific revision tag:

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

Replace

• TAG_NAME with the name of the tag you are migrating traffic to
• TRAFFIC_PERCENT with the percentage of traffic you want to the tagged revision to serve, for example, 1.

YAML

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

2. Make any chosen configuration changes to the service.

3. Below the spec attribute, locate and update the traffic attribute for the tagged revision so that the tagged revision serves only a small amount of traffic:

   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
   

   Note that the percentages must add up to 100. Replace

   • REVISION with the name of the tagged revision.
   • TAG_NAME with the name of the tag you are rolling out gradually.
   • PERCENT-NEW with the traffic percentage you want to send to the tagged revision, for example use 10 to send 10% of the traffic to that revision.
   • REVISION-FORMER with the name of the currently serving revision.
   • PERCENT-FORMER with the traffic percentage you want to send to the old revision

4. Replace the service with its new configuration using the following command:

   gcloud run services replace service.yaml

5. 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:

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

Over a period of hours or days, as needed, gradually update from one tag to the other, increasing the percentage as needed for the tagged revision.

Apply by entering terraform apply after every change.

Note: If the revision doesn't exist, you will receive the error: Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty.

What's next

• Learn about using Cloud Deploy to set up a continuous-delivery pipeline to deploy to Cloud Run.