Stay organized with collections
Save and categorize content based on your preferences.
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:
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 console, the Google Cloud CLI,
or Terraform:
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
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Configure labels for worker pools\n\n| **Preview\n| --- Cloud Run worker pools**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nCloud Run labels are key-value pairs that are applied to\nCloud Run worker pools. This page shows how to set, modify, and\ndelete labels on your Cloud Run worker pools.\nNote that when you set a label on a Cloud Run\nworker pool, a new revision with this label is created for this\nworker pool; the label is not applied to older revisions.\n\nPossible uses include:\n\n- Cost allocation and billing breakdowns.\n- Identify resources used by individual teams or cost centers.\n- Distinguish deployment environments (prod, staging, qa, or test).\n- Identify owners and state labels.\n- Filter logs in Logging.\n\nLabels usage rules\n------------------\n\nThe following rule applies to the use of labels set on a\nCloud Run worker pool:\n\nOnly [valid Google Cloud labels](/resource-manager/docs/creating-managing-labels) can be used on Cloud Run.\n\nRequired roles\n--------------\n\n\nTo get the permissions that\nyou need to configure and deploy Cloud Run worker pools,\n\nask your administrator to grant you the\nfollowing IAM roles:\n\n- [Cloud Run Developer](/iam/docs/roles-permissions/run#run.developer) (`roles/run.developer`) on the Cloud Run worker pool\n- [Service Account User](/iam/docs/roles-permissions/iam#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the service identity\n\n\nFor a list of IAM roles and permissions that are associated with\nCloud Run, see\n[Cloud Run IAM roles](/run/docs/reference/iam/roles)\nand [Cloud Run IAM permissions](/run/docs/reference/iam/permissions).\nIf your Cloud Run worker pool interfaces with\nGoogle Cloud APIs, such as Cloud Client Libraries, see the\n[service identity configuration guide](/run/docs/configuring/workerpools/service-identity).\nFor more information about granting roles, see\n[deployment permissions](/run/docs/reference/iam/roles#additional-configuration)\nand [manage access](/iam/docs/granting-changing-revoking-access).\n\nSet or modify labels\n--------------------\n\nAny configuration change leads to the\ncreation of a new revision. Subsequent revisions will also automatically get\nthis configuration setting unless you make explicit updates to change it.\n\nYou can set or modify labels using the Google Cloud console, the Google Cloud CLI,\nor Terraform: \n\n### Console\n\n1. In the Google Cloud console, go to Cloud Run:\n\n [Go to Cloud Run](https://console.cloud.google.com/run/worker-pools)\n2. Locate the worker pool and select the checkbox to the left of its name.\n\n3. Click **Labels** to display the Labels pane.\n\n4. To edit an existing label key value, locate the label and change the\n *Value* as desired.\n\n5. To set a new label on the worker pool, click **Add Label** and supply the key\n and the value.\n\n6. Click **Save**\n\n### gcloud\n\nYou can update labels for a worker pool using the command:\n\n\u003cbr /\u003e\n\n```bash\ngcloud beta run worker-pools update WORKER_POOL --update-labels KEY=VALUE\n```\n\n\u003cbr /\u003e\n\nTo update more than one label, supply a comma-delimited list of key and value\npairs. Note that the `update-labels` command sets a new value for the label\nkey if the label already exists, otherwise it creates a new label.\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eWORKER_POOL\u003c/var\u003e: the name of your Cloud Run worker pool\n- \u003cvar translate=\"no\"\u003eKEY\u003c/var\u003e: the name of your label key\n- \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e: the value for the key\n\nYou can also set labels during [deployment](/run/docs/deploy-worker-pools#worker-pool):\n\n\u003cbr /\u003e\n\n```bash\ngcloud beta run worker-pools deploy WORKER_POOL --image IMAGE --labels KEY=VALUE\n```\n\n\u003cbr /\u003e\n\nTo create more than one label during deployment, supply a comma-delimited\nlist of key and value pairs.\n\n### Terraform\n\n\u003cbr /\u003e\n\nTo learn how to apply or remove a Terraform configuration, see\n[Basic Terraform commands](/docs/terraform/basic-commands).\n\n\u003cbr /\u003e\n\n resource \"google_cloud_run_v2_worker_pool\" \"default\" {\n name = \"\u003cvar translate=\"no\"\u003eWORKER_POOL\u003c/var\u003e\"\n location = \"\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\"\n launch_stage = \"BETA\"\n\n template {\n containers {\n image = \"\u003cvar translate=\"no\"\u003eIMAGE_URL\u003c/var\u003e\"\n }\n }\n labels = {\n \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-err\"\u003eKEY\u003c/span\u003e\u003c/var\u003e : \"\u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e\"\n }\n }\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eWORKER_POOL\u003c/var\u003e: the name of the worker pool\n- \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: the Google Cloud region---for example, `europe-west1`\n- \u003cvar translate=\"no\"\u003eIMAGE_URL\u003c/var\u003e: a reference to the container image that contains the worker pool, such as `us-docker.pkg.dev/cloudrun/container/worker-pool:latest`\n- \u003cvar translate=\"no\"\u003eKEY\u003c/var\u003e: the name of your label key\n- \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e: the value for the key\n\nList services by label\n----------------------\n\nYou can list services by label using a\n[Google Cloud CLI filter](/sdk/gcloud/reference/topic/filters):\n\n\u003cbr /\u003e\n\n```bash\n gcloud beta run worker-pools list --filter metadata.labels.LABEL=VALUE\n \n```\n\n\u003cbr /\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eLABEL\u003c/var\u003e: the name of the label\n- \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e: the value to include in your filtered list\n\nDelete a label on a worker pool\n-------------------------------\n\nYou can use the Google Cloud console or the Google Cloud CLI to delete labels on a worker pool. \n\n### Console\n\n1. In the Google Cloud console, go to Cloud Run:\n\n [Go to Cloud Run](https://console.cloud.google.com/run/worker-pools)\n2. Locate the worker pool and select the checkbox to the left of its name.\n\n3. Click **Labels** to display the Labels pane.\n\n4. Locate the label you want to delete.\n\n5. To the right of the label's **Value** textbox, hover your cursor to\n display the trash icon, then click the trash icon.\n\n6. Click **Save**\n\n### gcloud\n\nTo clear all labels from a worker pool:\n\n\u003cbr /\u003e\n\n```bash\ngcloud beta run worker-pools update WORKER_POOL --clear-labels\n```\n\n\u003cbr /\u003e\n\nTo delete specific labels from a worker pool, supply a comma-delimited list of\nkeys:\n\n\u003cbr /\u003e\n\n```bash\ngcloud beta run worker-pools update WORKER_POOL --remove-labels LABEL\n```\n\n\u003cbr /\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eWORKER_POOL\u003c/var\u003e: the name of your Cloud Run worker pool\n- \u003cvar translate=\"no\"\u003eLABEL\u003c/var\u003e: the name of your label"]]