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 theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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

Cloud Run lets you specify which revisions receive instances andspecify instance allocation percentages for each revision. This feature lets youroll back to a previous revision, split instances between multiple revisions, andallocate instances to the latest revision. This page describes how to usethis feature to manage instance allocation to your Cloud Run revisions.

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

Lifecycle of instance splits

If you split instances between multiple revisions or assign instances to aprevious revision, all subsequent deployments use that instance split patterngoing forward. To return to just using the latest revision without instancesplitting,send all instances to the latestrevision.

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 theCloud Run Developer (roles/run.developer) IAM role on your Cloud Run worker pool.

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run worker pool interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Roll back to a previous revision

To roll back to a previous revision, use the Google Cloud console, orthe 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 theRevisions tab to show the list of current revisions for that worker pool.

  4. ClickManage 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 previousrevision.
    2. Set that previous revision's instance percentage to 100.
    3. Set the latest serving revision's percentage to 0.
    4. ClickSave.

gcloud

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

gcloudbetarunworker-poolsupdate-instance-splitWORKER_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, orthe Google Cloud CLI:

When you split instances between multiple revisions, make sure that the totalpercentage across all revisions equals 100%, and the number ofmanual instancesmust 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 theRevisions tab to show the list of current revisions forthat worker pool.

  4. ClickManage 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. ClickAdd revision and use the drop-down list to select a previousrevision and set its corresponding percentage split.

    3. To split instances with additional revisions, clickAdd Revision, andselect another revision, and set its percentage.

    4. ClickSave.

gcloud

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

gcloudbetarunworker-poolsupdate-instance-splitWORKER_POOL--to-revisions=LIST

Replace the following:

  • WORKER_POOL: the name of the worker pool.

  • LIST: comma delimited list of revisions andpercentages:

    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 thisrevision and all future ones, overriding any established instance split. Toallocate 100% of the instances to thelatestrevision,run the following commands:

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

    gcloudbetarunworker-poolsupdate-instance-splitWORKER_POOL--to-latest

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

    gcloudbetarunworker-poolsupdate-instance-splitWORKER_POOL--to-revisions=LATEST=PERCENTAGE

    Replace the following:

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.