Manual scaling for worker pools

Manual scaling lets you set a specific instance count without requiring redeployment. Use manual scaling when your workload needs a fixed number of instances, or when you want to control the instance count from your own system.

To scale instances automatically based on CPU utilization instead of setting a fixed instance count, see Configure CPU autoscaling for worker pools.

Billing considerations when using manual scaling

When you use manual scaling, all the instances that you requested are billed as active instances, even if they happen to be idle. For complete billing details, see the pricing page.

Required roles

To get the permissions that you need to configure and deploy Cloud Run worker pools, ask your administrator to grant you the following IAM roles:

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.

Configure scaling

Changing scaling mode or changing the manual instance count does not create a new revision.

To configure the scaling mode, use the Google Cloud console, the Google Cloud CLI, YAML, Terraform, or REST API:

Console

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

    Go to Cloud Run

  2. If you are configuring a new worker pool, select Worker pools from the menu, and click Deploy container. If you are configuring an existing worker pool, click the worker pool to display its detail pane, then click the pen icon next to Scaling at the top right of the detail panel.

  3. Locate the Scaling form (for a new worker pool) or the Edit scaling form for an existing worker pool.

    image

  4. In the field labelled Number of instances, specify the number of container instances for the worker pool.

  5. Finish the specification.

  6. Click Create for a new worker pool or Save for an existing worker pool.

gcloud

  • To specify manual scaling for a new worker pool, run the following command with the --scaling flag:
gcloud beta run worker-pools deploy WORKER_POOL \
    --scaling=INSTANCE_COUNT \
    --image IMAGE_URL

Replace the following:

  • WORKER_POOL: the name of your worker pool.
  • INSTANCE_COUNT: the number of instances for the worker pool. This sets the worker pool to manual scaling. Specify a value of 0 to disable 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.

  • To specify manual scaling for an existing worker pool, run the following command with the --scaling flag:

gcloud beta run worker-pools update WORKER_POOL \
    --scaling=INSTANCE_COUNT

Replace the following:

  • WORKER_POOL: the name of your worker pool.
  • INSTANCE_COUNT: the number of instances for the worker pool.

YAML

  1. 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 > worker-pool.yaml
  2. Set scalingMode to manual and specify manualInstanceCount:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
    name: WORKER_POOL
    annotations:
      run.googleapis.com/scalingMode: manual
      run.googleapis.com/manualInstanceCount: "INSTANCE_COUNT"

    Replace the following:

    • WORKER_POOL: the name of your Cloud Run worker pool.
    • INSTANCE_COUNT: the number of instances you are manually scaling for the worker pool. Specify a value of 0 to disable the worker pool.
  3. Create or update the worker pool using the following command:

    gcloud run worker-pools replace worker-pool.yaml

    The gcloud run worker-pools replace command defaults to using worker-pool.yaml file if present.

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"
    }
  }
  scaling {
    scaling_mode = "MANUAL"
    manual_instance_count = "INSTANCE_COUNT"
  }
}

Replace the following:

  • WORKER_POOL: the name of the worker pool.
  • REGION: the Google Cloud region—for example, europe-west1.
  • IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
  • INSTANCE_COUNT: the number of instances for the worker pool. This sets the worker pool to manual scaling. Specify a value of 0 to disable the worker pool.

REST API

To update the number of instances for a given worker pool, send a PATCH HTTP request to the Cloud Run Admin API workerPools.patch endpoint:

curl -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -X PATCH \
   -d '{"scaling":{"scalingMode":"MANUAL","manualInstanceCount":INSTANCE_COUNT}}' \
   https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=scaling.scalingMode,scaling.manualInstanceCount

Replace the following:

  • ACCESS_TOKEN: a valid access token for an account that has the IAM permissions to update a worker pool. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
  • INSTANCE_COUNT: the number of instances for the worker pool.
  • PROJECT_ID: the Google Cloud project ID.
  • REGION: the Google Cloud region that the worker pool is deployed in.
  • WORKER_POOL: the name of the worker pool.

View scaling configuration for a worker pool

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

    Go to Cloud Run

  2. Click Worker pools to display the list of deployed worker pools.

  3. Click the worker pool you want to examine to display its details pane.

  4. The current scaling setting is shown above the worker pools revision list: Scaling: Manual (Instances: ).

Disable a worker pool

To disable a worker pool, run the following command with the --scaling=0 flag:

gcloud beta run worker-pools update WORKER_POOL --scaling=0

Replace WORKER_POOL with the name of your worker pool.

What's next