Configure memory limits for worker pools

You can choose the amount of memory to provide for your Cloud Run worker pool. This page describes how to specify the amount of memory available for your worker pool.

Understand memory usage

Cloud Run instances that exceed their allowed memory limit are terminated.

The available memory for your instance needs to be sufficient for:

  • Running the worker pool executable, because the executable must be loaded to memory
  • Allocating memory in your worker pool process
  • Writing files to the file system

The size of the deployed container image does not affect memory that is available for the instance.

Set and update memory limits

You can set memory limits on Cloud Run worker pools. By default, the memory allocated to each worker pool is 512 MiB.

Required minimum CPUs

The amount of allocated memory you choose corresponds to an amount of minimum CPU for your worker pool. When setting a memory limit, the following minimum CPU limits are required:

Memory Minimum CPUs required
2 GiB 1 vCPU
More than 4 GiB 2 vCPU
More than 8 GiB 4 vCPU
More than 16 GiB 6 vCPU
More than 24 GiB 8 vCPU

Maximum amount of memory

The maximum amount of memory you can configure is 32 gibibyte (32 Gi).

You can enforce a maximum memory limit by using custom organization policies.

Minimum memory

The minimum memory setting is 512 MiB.

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 memory limits

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

You can set memory limits for a Cloud Run worker pool using the Google Cloud console, Google Cloud CLI, YAML, or Terraform:

Console

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

    Go to Cloud Run

  2. Select Worker pools from the menu, and click Deploy container to configure a new worker pool. If you are configuring an existing worker pool, click the worker pool, then click Edit and deploy new revision.

  3. If you are configuring a new worker pool, fill out the initial worker pool page, then click Container(s), Volumes, Networking, Security to expand the worker pools configuration page.

  4. Click the Container tab.

    image

    • Select the memory size from the Memory list.

  5. Click Create or Deploy.

gcloud

You can update the memory allocation of a given worker pool by using the following command:

gcloud beta run worker-pools update WORKER_POOL --memory SIZE

Replace the following:

  • WORKER_POOL: the name of your worker pool
  • SIZE: a memory size from the CPU and memory table. The format for size is a fixed or floating point number followed by a unit: G or M corresponding to gigabyte or megabyte, respectively, or use the power-of-two equivalents: Gi or Mi corresponding to gibibyte or mebibyte respectively.

You can also set memory limits during deployment using the command:

gcloud beta run worker-pools deploy --image IMAGE_URL --memory SIZE

Replace the following:

  • IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
  • SIZE: a memory size from the CPU and memory table. The format for size is a fixed or floating point number followed by a unit: G or M corresponding to gigabyte or megabyte, respectively, or use the power-of-two equivalents: Gi or Mi corresponding to gibibyte or mebibyte respectively.

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 beta run worker-pools describe WORKER_POOL --format export > workerpool.yaml

  2. The following example contains the YAML configuration:

    apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
  name: WORKER_POOL
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
        resources:
          limits:
            memory: SIZE

    Replace the following:

    • WORKER_POOL: the name of your Cloud Run 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.
    • SIZE: the chosen memory size. The format is a fixed or floating point number followed by a unit: G or M corresponding to gigabyte or megabyte, respectively, or use the power-of-two equivalents: Gi or Mi corresponding to gibibyte or mebibyte respectively.

  3. Create or update the worker pool using the following command:

    gcloud beta 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"
  launch_stage = "BETA"

  template {
    containers {
      image = "IMAGE_URL"
      resources {
        limits = {
          memory = "SIZE"
        }
      }
    }
  }
}

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
  • SIZE: a memory size from the CPU and memory table. The format for size is a fixed or floating point number followed by a unit: G or M corresponding to gigabyte or megabyte, respectively, or use the power-of-two equivalents: Gi or Mi corresponding to gibibyte or mebibyte respectively.

View memory configuration for the 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. Click the Containers tab to display worker pool memory configuration for each container.