Configure labels for worker pools

Cloud Run labels are key-value pairs that are applied to Cloud Run worker pools. This page shows how to set, modify, and delete labels on your Cloud Run worker pools. Note that when you set a label on a Cloud Run worker pool, a new revision with this label is created for this worker 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 a Cloud Run worker pool:

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

Set or modify labels

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 or modify labels using the Google Cloud CLI or Terraform:

gcloud

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

gcloud beta run worker-pools update WORKER_POOL --update-labels KEY=VALUE

To update more than one label, supply a comma-delimited list of key and value pairs. Note that the update-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 during deployment:

gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE --labels KEY=VALUE

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

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"
    }
  }
  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 with a reference to the container image that contains the worker pool, such as us-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 a Google Cloud CLI filter:

  gcloud beta run worker-pools list --filter metadata.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 CLI to delete labels on a worker pool.

gcloud

To clear all labels from a worker pool:

gcloud beta run worker-pools update WORKER_POOL --clear-labels

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

gcloud beta run worker-pools update WORKER_POOL --remove-labels LABEL

Replace the following:

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