Instance splits and rollbacks for Cloud Run worker pools

Preview — Cloud Run worker pools

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Worker Pools handle non-request workloads. For use cases that need to split work between multiple revisions, such as deploying a new revision, worker pools use instance splitting.

Cloud Run lets you specify which revisions receive instances and specify instance allocation percentages for each revision. This feature lets you roll back to a previous revision, split instances between multiple revisions, and allocate instances to the latest revision. This page describes how to use this feature to manage instance allocation to your Cloud Run revisions.

Instance allocation adjustments are not instantaneous. When you change instance allocation for revisions, all requests being processed continue to completion. In-flight requests aren't dropped, and Cloud Run might direct these requests to either a new revision or a previous revision during the transition period.

Lifecycle of instance splits

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

Required roles

To get the permissions that you need to manage Cloud Run worker pools and worker pool revisions, ask your administrator to grant you the Cloud Run Developer (roles/run.developer) IAM role on your Cloud Run worker pool.

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 worker pool 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, use the Google Cloud console, or the Google Cloud CLI:

Console

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

   Go to Cloud Run

2. Locate the worker pool in the list, and click it.

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

4. Click Manage instance splits to display the manage instances form. Cloud Run lists the latest serving revision. In the form, configure the following details:

   1. Add revision and use the drop-down list to select a previous revision.
   2. Set that previous revision's instance percentage to 100.
   3. Set the latest serving revision's percentage to 0.
   4. Click Save.

gcloud

Specify the revisions to rollback to by running the following command.

   gcloud beta run worker-pools update-instance-split WORKER_POOL --to-revisions=REVISION=100

Replace the following:

• WORKER_POOL: the name of the worker pool.
• REVISION: the name of the revision you are rolling back to.

Split instances between multiple revisions

To split instances between two or more revisions, use the Google Cloud console, or the Google Cloud CLI:

When you split instances between multiple revisions, make sure that the total percentage across all revisions equals 100%, and the number of manual instances must be greater than the number of instance splits serving the workload.

Console

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

   Go to Cloud Run

2. Locate the worker pool in the list, and click it.

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

4. Click Manage instance splits to display the manage instances form. Cloud Run lists the latest serving revision. In the form, configure the following details:

   1. Set the latest serving revision's percentage to the required split, for example, reduce it from 100%.

   2. Click Add revision and use the drop-down list to select a previous revision and set its corresponding percentage split.

   3. To split instances with additional revisions, click Add Revision, and select another revision, and set its percentage.

   4. Click Save.

gcloud

Specify the revisions and the percentage of instances by running the following command. Allocate instances for each revision in a comma delimited list:

   gcloud beta run worker-pools update-instance-split WORKER_POOL --to-revisions=LIST

Replace the following:

• WORKER_POOL: the name of the worker pool.

• LIST: comma delimited list of revisions and percentages:

  REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx.

  For example, my-worker-pool-s5sxn=10,my-worker-pool-cp9kw=90.

Allocate instances to the latest revision

When you deploy a new revision, you can allocate 100% of instances to this revision and all future ones, overriding any established instance split. To allocate 100% of the instances to the latest revision, run the following commands:

• Use the --to-latest flag to direct 100% of instances to the latest revision and automatically allocate all instances to any new revision you deploy:

  gcloud beta run worker-pools update-instance-split WORKER_POOL --to-latest
  

• Optionally, use the --to-revisions flag with the LATEST keyword to always allocate a floating percentage of instances to the newest revision when you deploy one. To set a percentage of instances that always float to the latest revision, run the following command:

  gcloud beta run worker-pools update-instance-split WORKER_POOL --to-revisions=LATEST=PERCENTAGE
  

  Replace the following:

  • WORKER_POOL: the name of the worker pool.
  • PERCENTAGE: the percentage of instances to allocate for the latest and future latest revisions.

What's next

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