Instance splits and rollbacks for Cloud Run worker pools

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

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

Go to Cloud Run
Locate the worker pool in the list, and click it.
Click the Revisions tab to show the list of current revisions for that worker pool.
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 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.

YAML

If you are creating a new worker pool, skip this step. If you are updating an existing worker pool, download its YAML configuration:
```
gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml
```
The following example contains the YAML configuration:
```
apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - revisionName: REVISION
    percent: 100
```
Replace the following:
- WORKER_POOL: the name of the worker pool.
- REGION: the Google Cloud region—for example, us-central1.
- IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest
- REVISION: the name of the revision you are rolling back to.
Create or update the worker pool using the following command:
```
gcloud run worker-pools replace workerpool.yaml
```

Terraform

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

import {
  id = "projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL"
  to = google_cloud_run_v2_worker_pool.default
}

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION"
    percent  = 100
  }
}

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
REGION: the Google Cloud region—for example, us-central1.
WORKER_POOL: the name of the worker pool.
IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest
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

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

Go to Cloud Run
Locate the worker pool in the list, and click it.
Click the Revisions tab to show the list of current revisions for that worker pool.
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 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.

YAML

If you are creating a new worker pool, skip this step. If you are updating an existing worker pool, download its YAML configuration:
```
gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml
```
The following example contains the YAML configuration:
```
apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/scalingMode: manual
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - revisionName: REVISION1
    percent: PERCENTAGE1
  - revisionName: REVISION2
    percent: PERCENTAGE2
```
Replace the following:
- WORKER_POOL: the name of the worker pool.
- REGION: the Google Cloud region—for example, us-central1.
- INSTANCE_COUNT: the number of instances.
- IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest
- REVISION1 and REVISION2: the name of the revisions.
- PERCENTAGE1 and PERCENTAGE2: the percentage of instances to allocate to each of these revisions. These need to add up to 100.
Create or update the worker pool using the following command:
```
gcloud run worker-pools replace workerpool.yaml
```

Terraform

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

import {
  id = "projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL"
  to = google_cloud_run_v2_worker_pool.default
}

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION1"
    percent  = PERCENTAGE1
  }
  instance_splits {
    type     = "INSTANCE_SPLIT_ALLOCATION_TYPE_REVISION"
    revision = "REVISION2"
    percent  = PERCENTAGE2
  }
}

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
REGION: the Google Cloud region—for example, us-central1.
WORKER_POOL: the name of the worker pool.
IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest
REVISION1 and REVISION2: the name of the revisions.
PERCENTAGE1 and PERCENTAGE2: the percentage of instances to allocate to each of these revisions. These need to add up to 100.

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.

gcloud

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

YAML

If you are creating a new worker pool, skip this step. If you are updating an existing worker pool, download its YAML configuration:
```
gcloud run worker-pools describe WORKER_POOL --format export > workerpool.yaml
```

The following example contains the YAML configuration:

apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  labels:
    cloud.googleapis.com/location: REGION
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
  instanceSplits:
  - latestRevision: true
    percent: 100

Replace the following:

WORKER_POOL: the name of the worker pool.
REGION: the Google Cloud region—for example, us-central1.
IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest

Create or update the worker pool using the following command:
```
gcloud run worker-pools replace workerpool.yaml
```

Terraform

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

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }

  instance_splits {
    type = "INSTANCE_SPLIT_ALLOCATION_TYPE_LATEST"
    percent  = 100
  }
}

Replace the following:

WORKER_POOL: the name of the worker pool.
REGION: the Google Cloud region—for example, us-central1.
IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest

What's next

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

Instance splits and rollbacks for Cloud Run worker pools Stay organized with collections Save and categorize content based on your preferences.

Lifecycle of instance splits

Required roles

Roll back to a previous revision

Console

gcloud

YAML

Terraform

Split instances between multiple revisions

Console

gcloud

YAML

Terraform

Allocate instances to the latest revision

gcloud

YAML

Terraform

What's next

Instance splits and rollbacks for Cloud Run worker pools