Configure labels for 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.

Cloud Run labels are key-value pairs that are applied toCloud Run worker pools. This page shows how to set, modify, anddelete labels on your Cloud Run worker pools.Note that when you set a label on a Cloud Runworker pool, a new revision with this label is created for thisworker pool; the label is not applied to older revisions.

Possible uses include:

  • Cost allocation and billing breakdowns.
  • Identify resources used by individual teams or cost centers.
  • Distinguish deployment environments (prod, staging, qa, or test).
  • Identify owners and state labels.
  • Filter logs in Logging.

Labels usage rules

The following rule applies to the use of labels set on aCloud Run worker pool:

Onlyvalid Google Cloud labels can be used on Cloud Run.

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

Set or modify labels

Any configuration change leads to thecreation of a new revision. Subsequent revisions will also automatically getthis configuration setting unless you make explicit updates to change it.

You can set or modify labels using the Google Cloud console, the Google Cloud CLI,or Terraform:

Console

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

    Go to Cloud Run

  2. Locate the worker pool and select the checkbox to the left of its name.

  3. ClickLabels to display the Labels pane.

    Set label

  4. To edit an existing label key value, locate the label and change theValue as desired.

  5. To set a new label on the worker pool, clickAdd Label and supply the keyand the value.

  6. ClickSave

gcloud

You can update labels for a worker pool using the command:

gcloudbetarunworker-poolsupdateWORKER_POOL--update-labelsKEY=VALUE

To update more than one label, supply a comma-delimited list of key and value pairs. Note that theupdate-labels command sets a new value for the label key if the label already exists, otherwise it creates a new label.

Replace the following:

  • WORKER_POOL: the name of your Cloud Run worker pool
  • KEY: the name of your label key
  • VALUE: the value for the key

You can also set labels duringdeployment:

gcloudbetarunworker-poolsdeployWORKER_POOL--imageIMAGE--labelsKEY=VALUE

To create more than one label during deployment, supply a comma-delimitedlist of key and value pairs.

YAML

  1. If you are creating a new worker pool, skip this step.If you are updating an existing worker pool, download itsYAML configuration:

    gcloudbetarunworker-poolsdescribeWORKER_POOL--formatexport>workerpool.yaml

  2. The following example contains the YAML configuration:

    apiVersion:run.googleapis.com/v1kind:WorkerPoolmetadata:name:WORKER_POOLlabels:KEY:VALUEKEY2:VALUE2KEY3:VALUE3annotations:run.googleapis.com/launch-stage:BETA

    Replace the following:

    • WORKER_POOL: the name of your Cloud Run worker pool
    • KEY andVALUE: the key and value pairs for labels

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

    gcloudbetarunworker-poolsreplaceworkerpool.yaml

Terraform

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

resource"google_cloud_run_v2_worker_pool""default"{name="WORKER_POOL"location="REGION"launch_stage="BETA"template{containers{image="IMAGE_URL"}}labels={KEY:"VALUE"}}

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 thatcontains the worker pool, such asus-docker.pkg.dev/cloudrun/container/worker-pool:latest
  • KEY: the name of your label key
  • VALUE: the value for the key

List services by label

You can list services by label using aGoogle Cloud CLI filter:

gcloudbetarunworker-poolslist--filtermetadata.labels.LABEL=VALUE

Replace the following:

  • LABEL: the name of the label
  • VALUE: the value to include in your filtered list

Delete a label on a worker pool

You can use the Google Cloud console or the Google Cloud CLI to delete labels on a worker pool.

Console

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

    Go to Cloud Run

  2. Locate the worker pool and select the checkbox to the left of its name.

  3. ClickLabels to display the Labels pane.

    Set label

  4. Locate the label you want to delete.

  5. To the right of the label'sValue textbox, hover your cursor todisplay the trash icon, then click the trash icon.

  6. ClickSave

gcloud

To clear all labels from a worker pool:

gcloudbetarunworker-poolsupdateWORKER_POOL--clear-labels

To delete specific labels from a worker pool, supply a comma-delimited list ofkeys:

gcloudbetarunworker-poolsupdateWORKER_POOL--remove-labelsLABEL

Replace the following:

  • WORKER_POOL: the name of your Cloud Run worker pool
  • LABEL: the name of your label

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 2026-02-19 UTC.