Configure CPU autoscaling for worker pools

CPU autoscaling in Cloud Run worker pools lets you scale instances based on the average CPU utilization to optimize performance and cost. You can configure autoscaling with the default CPU utilization target or specify custom CPU utilization targets and instance limits. For more information about how Cloud Run calculates instance counts and scales worker pools, see About CPU autoscaling.

When you deploy a worker pool without enabling CPU autoscaling, Cloud Run uses manual scaling with 1 instance by default.

If you use Cloud Run External Metrics Autoscaling (CREMA) to scale your workloads, switch to manual scaling.

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 the default CPU target

When you enable default CPU autoscaling, Cloud Run targets 60% CPU utilization and scales your worker pool between 1 and 100 instances. While keeping the default 60% CPU utilization target, you can optionally customize the minimum and maximum instance limits to fit your needs.

Updating the scaling mode or instance limits on an existing worker pool doesn't create a new revision.

You can enable default CPU autoscaling for a Cloud Run worker pool using the Google Cloud CLI, YAML, or the REST API:

gcloud

  • To deploy a new worker pool with the default CPU target, run the following command with the --scaling=auto flag:

    gcloud beta run worker-pools deploy WORKER_POOL \
      --image=IMAGE_URL \
      --scaling=auto

    Replace the following:

    • WORKER_POOL: the name of your 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 update an existing worker pool to use the default CPU target, run the following command with the --scaling=auto flag:

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

    Replace WORKER_POOL with the name of your worker pool.

  • To update an existing worker pool with the default CPU target and custom instance limits, run the following command with the --scaling=auto, --min, and --max flags:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling=auto \
      --min=MIN_INSTANCES \
      --max=MAX_INSTANCES

    Replace the following:

    • WORKER_POOL: the name of your worker pool.
    • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
    • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.

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. Add or update the launch-stage and scalingMode annotations under metadata.annotations, and remove the run.googleapis.com/manualInstanceCount annotation if present. To set custom instance limits, optionally add the minScale and maxScale annotations:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic
       run.googleapis.com/minScale: 'MIN_INSTANCES'
       run.googleapis.com/maxScale: 'MAX_INSTANCES'

    Replace the following:

    • WORKER_POOL: the name of your worker pool.
    • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
    • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.
  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.

REST API

To configure the default CPU target on an existing worker pool, send the following PATCH HTTP request to the Cloud Run Admin API workerPools.patch endpoint. To set custom instance limits, optionally include the minInstanceCount and maxInstanceCount fields and their update_mask paths:

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

Replace the following:

  • ACCESS_TOKEN: a valid access token for an account that has the Identity and Access Management permissions to update a worker pool. For example, if you are signed in to the Google Cloud CLI, you can retrieve an access token by running gcloud auth print-access-token.
  • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
  • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.
  • PROJECT_ID: your Google Cloud project ID.
  • REGION: the Google Cloud region where your worker pool is deployed, for example, europe-west1.
  • WORKER_POOL: the name of your worker pool.

Configure custom CPU targets and instance limits

You can customize the CPU utilization target, the minimum and maximum instance limits, or both. Any setting that you omit uses its default value (60% CPU target, 1 minimum instance, and 100 maximum instances). Updating the CPU utilization target or instance limits on an existing worker pool doesn't create a new revision.

You can configure custom CPU targets and instance limits using the Google Cloud CLI, YAML, or the REST API:

gcloud

  • To deploy a new worker pool with a custom CPU target, run the following command with the --scaling-cpu-target flag:

    gcloud beta run worker-pools deploy WORKER_POOL \
      --image=IMAGE_URL \
      --scaling-cpu-target=CPU_TARGET

    Replace the following:

    • WORKER_POOL: the name of your 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.
    • CPU_TARGET: the target for CPU utilization. Specify a value from 0.1 to 0.90.
  • To update an existing worker pool with a custom CPU target, run the following command with the --scaling-cpu-target flag:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=CPU_TARGET

    Replace the following:

    • WORKER_POOL: the name of your worker pool.
    • CPU_TARGET: the target for CPU utilization. Specify a value from 0.1 to 0.90.
  • To update an existing worker pool with a custom CPU target and instance limits, run the following command with the --scaling-cpu-target, --min, and --max flags:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=CPU_TARGET \
      --min=MIN_INSTANCES \
      --max=MAX_INSTANCES

    Replace the following:

    • WORKER_POOL: the name of your worker pool.
    • CPU_TARGET: the target for CPU utilization. Specify a value from 0.1 to 0.90.
    • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
    • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.

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. Add or update the launch-stage, scalingMode, scaling-cpu-target, minScale, and maxScale annotations under metadata.annotations, and remove the run.googleapis.com/manualInstanceCount annotation if present. You can omit any custom annotation (scaling-cpu-target, minScale, or maxScale) that you want to keep at its default value:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic
       run.googleapis.com/scaling-cpu-target: 'CPU_TARGET'
       run.googleapis.com/minScale: 'MIN_INSTANCES'
       run.googleapis.com/maxScale: 'MAX_INSTANCES'

    Replace the following:

    • WORKER_POOL: the name of your worker pool.
    • CPU_TARGET: the target for CPU utilization. Specify a value from 0.1 to 0.90.
    • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
    • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.
  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.

REST API

To configure a custom CPU target and custom instance limits on an existing worker pool, send the following 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 '{"launchStage":"BETA","scaling":{"scalingMode":"AUTOMATIC","cpuScaling":{"cpuUtilization":CPU_TARGET},"minInstanceCount":MIN_INSTANCES,"maxInstanceCount":MAX_INSTANCES}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=launchStage,scaling.scalingMode,scaling.manualInstanceCount,scaling.cpuScaling.cpuUtilization,scaling.minInstanceCount,scaling.maxInstanceCount

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 signed in to the Google Cloud CLI, you can retrieve an access token by running gcloud auth print-access-token.
  • CPU_TARGET: the target for CPU utilization. Specify a value from 0.1 to 0.90.
  • Optional: MIN_INSTANCES: the minimum number of container instances to run for the worker pool. Must be 1 or greater. If you omit this value, Cloud Run sets the minimum to 1 instance.
  • Optional: MAX_INSTANCES: the maximum number of container instances to run for the worker pool. If you omit this value, Cloud Run sets the maximum to 100 instances.
  • PROJECT_ID: your Google Cloud project ID.
  • REGION: the Google Cloud region where your worker pool is deployed, for example, europe-west1.
  • WORKER_POOL: the name of your worker pool.

Restore default autoscaling settings

When you restore a custom CPU utilization target or custom instance limits to their default values, Cloud Run reverts to the default target of 60% CPU utilization, 1 minimum instance, and 100 maximum instances while keeping CPU autoscaling active.

You can restore default autoscaling settings using the Google Cloud CLI, YAML, or the REST API:

gcloud

  • To restore the default CPU target, run the following command with the --scaling-cpu-target=default flag:

    gcloud beta run worker-pools update WORKER_POOL \
      --scaling-cpu-target=default

    Replace WORKER_POOL with the name of your worker pool.

  • To restore the default instance limits, run the following command with the --min=default and --max=default flags:

    gcloud beta run worker-pools update WORKER_POOL \
      --min=default \
      --max=default

    Replace WORKER_POOL with the name of your 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. Remove the scaling-cpu-target, minScale, and maxScale annotations from metadata.annotations. Update the scalingMode: automatic annotation:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
     name: WORKER_POOL
     annotations:
       run.googleapis.com/launch-stage: BETA
       run.googleapis.com/scalingMode: automatic

    Replace WORKER_POOL with the name of your 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.

REST API

To restore the default CPU target and default instance limits on an existing worker pool, send the following 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 '{"launchStage":"BETA","scaling":{"scalingMode":"AUTOMATIC","cpuScaling":{}}}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/workerPools/WORKER_POOL?update_mask=launchStage,scaling.scalingMode,scaling.cpuScaling.cpuUtilization,scaling.minInstanceCount,scaling.maxInstanceCount

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 signed in to the Google Cloud CLI, you can retrieve an access token by running gcloud auth print-access-token.
  • PROJECT_ID: your Google Cloud project ID.
  • REGION: the Google Cloud region where your worker pool is deployed, for example, europe-west1.
  • WORKER_POOL: the name of your worker pool.

Disable CPU autoscaling

To disable CPU autoscaling and switch your worker pool back to manual scaling, specify a fixed instance count using the Google Cloud CLI, YAML, or the REST API:

gcloud

To disable CPU autoscaling on an existing worker pool, run the following command with the --scaling flag set to your fixed instance count:

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 fixed number of instances to run in manual scaling mode.

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, specify manualInstanceCount, and remove scaling-cpu-target, minScale, and maxScale if present:

    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 worker pool.
    • INSTANCE_COUNT: the fixed number of instances to run in manual scaling mode.
  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.

REST API

To disable CPU autoscaling on an existing worker pool, send the following 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,scaling.cpuScaling,scaling.minInstanceCount,scaling.maxInstanceCount

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 signed in to the Google Cloud CLI, you can retrieve an access token by running gcloud auth print-access-token.
  • INSTANCE_COUNT: the fixed number of instances to run in manual scaling mode.
  • PROJECT_ID: your Google Cloud project ID.
  • REGION: the Google Cloud region where your worker pool is deployed, for example, europe-west1.
  • WORKER_POOL: the name of your worker pool.

View CPU autoscaling settings

To view the CPU autoscaling configuration for your worker pool, run the gcloud beta run worker-pools describe command:

gcloud beta run worker-pools describe WORKER_POOL

Replace WORKER_POOL with the name of your worker pool.

About CPU autoscaling

By default, CPU autoscaling targets 60% average CPU utilization (run.googleapis.com/container/cpu/utilizations) and scales your worker pool between 1 and 100 instances.

When you enable CPU autoscaling, Cloud Run calculates the required number of instances for the worker pool by averaging the CPU usage per second over the past minute across all running instances, and divides that value by the number of CPUs per instance. The result is then further divided by your CPU target:

\[ \text{Instances} = \left\lceil \dfrac{\left( \frac{\text{Average CPU usage per second over the past minute}}{\text{Number of CPUs per instance}} \right)}{\text{CPU target}} \right\rceil \]

Cloud Run adjusts the number of worker pool instances using the following behaviors:

  • Rounding up: Cloud Run calculates the required instance count from measured CPU usage and your target, not from the number of running instances, and rounds the result up to the next whole instance. Because of this rounding, your worker pool can scale up while utilization is still below your target. For example, a worker pool that needs 4.1 instances runs 5 instances.
  • Pool-level scaling and instance splits: Cloud Run calculates the total instance count for the entire worker pool and then distributes those instances across active revisions based on your configured instance splits.
  • 5-minute scale-down stabilization: Cloud Run uses a 5-minute (300-second) stabilization window when scaling down. To prevent frequent instance fluctuations, Cloud Run keeps the instance count at the highest recommendation from the preceding 5 minutes.

Choose a CPU utilization target

You can use the default 60% CPU utilization target or configure a custom target from 10% to 90% based on your workload profile and latency tolerance using the following guidelines:

  • Higher CPU target (80% to 90%): Use a higher target for steady, predictable background workloads or batch processing tasks that aren't latency-sensitive. A higher target maximizes resource utilization and reduces infrastructure cost, but leaves less headroom for sudden bursts of work, which can lead to CPU throttling or increased processing latency while new instances start.
  • Lower CPU target (20% to 40%): Use a lower target for workloads with spiky or unpredictable CPU demand, strict processing latency requirements, or longer container startup times. A lower target provides a buffer to absorb sudden activity spikes by provisioning more instances earlier, helping prevent performance degradation. The trade-off is higher cost because more instances run under normal load conditions.

We recommend that you start with the default target, monitor the run.googleapis.com/container/instance_count metric in Cloud Monitoring, and adjust your target based on load testing and performance observations.

What's next