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 service and revisions. This page shows how to set, modify, and
delete labels on your Cloud Run service and revisions.
Note that when you set a label on a Cloud Run
service, a new revision with this label is created for this
service; 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 service:
If you are deploying a service
or function from source code, you
must also have additional roles granted to you on your project and
Cloud Build service account.
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.
Labels you previously set for your Cloud Run functions using either
gcloud functions commands or the Cloud Functions v2 API propagate to Cloud Run when you deploy your functions in Cloud Run.
You can set or modify labels using the Google Cloud console, the gcloud
command line, or a YAML file when you
deploy a new revision.
To update more than one label, supply a comma delimited list of key/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.
REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
Starts with SERVICE-
Contains only lowercase letters, numbers and -
Does not end with a -
Does not exceed 63 characters
metadata.labels sets labels on the service object, while
spec.template.metadata.label sets labels on the created revision.
Only labels set on the revision are passed to logs and billing.
Create or update the service using the following command:
resource"google_cloud_run_v2_service""default"{name="cloudrun-service-labels"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{image="us-docker.pkg.dev/cloudrun/container/hello"} # Labelslabels={foo:"bar"baz:"quux"}}}
The preceding snippet adds two labels, foo (whose value is bar) and baz
(whose value is quux), to your Cloud Run instance.
Adding the labels under template sets the labels for the revision: only
labels set for the revision are passed to logs and billing. If you add the
labels to a location other than under template, the label is set for the
service not the revision.
Replace the:
name property with the name of your service.
location property with the location used for your service.
[[["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-28 UTC."],[],[],null,["# Configure labels for services\n\nCloud Run labels are key-value pairs that are applied to\nCloud Run service and revisions. This page shows how to set, modify, and\ndelete labels on your Cloud Run service and revisions.\nNote that when you set a label on a Cloud Run\nservice, a new revision with this label is created for this\nservice; 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 service:\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 services,\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 service\n- [Service Account User](/iam/docs/roles-permissions/iam#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the service identity\n\n\nIf you are deploying a [service](/run/docs/deploying-source-code#required_roles)\nor [function](/run/docs/deploy-functions#required-roles) from source code, you\nmust also have additional roles granted to you on your project and\nCloud Build service account.\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 service interfaces with\nGoogle Cloud APIs, such as Cloud Client Libraries, see the\n[service identity configuration guide](/run/docs/configuring/services/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\nLabels you previously set for your Cloud Run functions using either\n`gcloud functions` commands or the Cloud Functions v2 API propagate to Cloud Run when you [deploy your functions in Cloud Run](/run/docs/deploy-functions).\n\nYou can set or modify labels using the Google Cloud console, the gcloud\ncommand line, or a YAML file when you\n[deploy a new revision](/run/docs/deploying#revision). \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)\n2. Check the checkbox at the left of the service you are setting the label\n on.\n\n3. Make sure the *Info Panel* at the far right is toggled on\n (**Show Info Panel**).\n\n4. Click **Labels** to display the labels pane.\n\n5. To edit an existing label key value, locate the label and change the\n *Value* as desired.\n\n6. To set a new label on the service, click **Add Label** and supply the key\n and the value.\n\n7. Click **Save**\n\n### gcloud\n\nYou can update labels for a service using the command:\n\n\u003cbr /\u003e\n\n```bash\ngcloud run services update SERVICE --update-labels KEY=VALUE\n```\n\n\u003cbr /\u003e\n\nTo update more than one label, supply a comma delimited list of key/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\n\n- \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with name of your Cloud Run service\n- \u003cvar translate=\"no\"\u003eKEY\u003c/var\u003e with the name of your label key\n- \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e with the value for the key\n\nYou can also set labels during [deployment](/run/docs/deploying#service):\n\n\u003cbr /\u003e\n\n```bash\ngcloud run deploy SERVICE --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/value pairs.\n\n### YAML\n\n1. If you are creating a new service, skip this step.\n If you are updating an existing service, download its [YAML configuration](/run/docs/reference/yaml/v1):\n\n ```bash\n gcloud run services describe SERVICE --format export \u003e service.yaml\n ```\n2. Update the `labels` attributes in two places:\n\n ```yaml\n apiVersion: serving.knative.dev/v1\n kind: Service\n metadata:\n name: SERVICE\n labels:\n LABEL: VALUE\n spec:\n template:\n metadata:\n labels:\n LABEL: VALUE\n name: REVISION\n ```\n\n Replace\n - \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with the name of your Cloud Run service\n - \u003cvar translate=\"no\"\u003eLABEL\u003c/var\u003e with the name of the label\n - \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e with the desired value\n - \u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e with a new revision name or delete it (if present). If you supply a new revision name, it **must** meet the following criteria:\n - Starts with \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e`-`\n - Contains only lowercase letters, numbers and `-`\n - Does not end with a `-`\n - Does not exceed 63 characters\n\n `metadata.labels` sets labels on the service object, while\n `spec.template.metadata.label` sets labels on the created revision.\n Only labels set on the revision are passed to logs and billing.\n3. Create or update the service using the following command:\n\n ```bash\n gcloud run services replace service.yaml\n ```\n\n### Terraform\n\n\nTo learn how to apply or remove a Terraform configuration, see\n[Basic Terraform commands](/docs/terraform/basic-commands).\nAdd the following to a [`google_cloud_run_v2_service`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service) resource in your Terraform configuration: \n\n\u003cbr /\u003e\n\n resource \"google_cloud_run_v2_service\" \"default\" {\n name = \"cloudrun-service-labels\"\n location = \"us-central1\"\n\n deletion_protection = false # set to \"true\" in production\n\n template {\n containers {\n image = \"us-docker.pkg.dev/cloudrun/container/hello\"\n }\n # Labels\n labels = {\n foo : \"bar\"\n baz : \"quux\"\n }\n }\n }\n\nThe preceding snippet adds two labels, `foo` (whose value is `bar`) and `baz`\n(whose value is `quux`), to your Cloud Run instance.\n\nAdding the labels under `template` sets the labels for the revision: only\nlabels set for the revision are passed to logs and billing. If you add the\nlabels to a location other than under `template`, the label is set for the\nservice not the revision.\n\nReplace the:\n\n- `name` property with the name of your service.\n- `location` property with the location used for your service.\n- `image` property with your container image.\n- `foo` and `baz` with your own label names.\n- `bar` and `quux` with your own label values.\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 run services list --filter metadata.labels.LABEL=VALUE\n \n```\n\n\u003cbr /\u003e\n\nReplace:\n\n- \u003cvar translate=\"no\"\u003eLABEL\u003c/var\u003e with the name of the label\n- \u003cvar translate=\"no\"\u003eVALUE\u003c/var\u003e with the value to include in your filtered list\n\nDelete a label on a service\n---------------------------\n\nYou can use the console or the command line delete labels on a service. \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)\n2. Check the checkbox at the left of the service you are deleting the label\n from.\n\n3. Make sure the *Info Panel* at the far right is toggled on\n (**Show Info Panel**).\n\n4. Click **Labels** to display the labels pane.\n\n5. Locate the label you want to delete.\n\n6. Hover your cursor to the right of the *Value* textbox for the label to\n display the trash icon, and click the trash icon.\n\n7. Click **Save**\n\n### gcloud\n\nTo clear all labels from a service:\n\n\u003cbr /\u003e\n\n```bash\ngcloud run services update SERVICE --clear-labels\n```\n\n\u003cbr /\u003e\n\nTo delete specific labels from a service, supply a comma delimited list of\nkeys:\n\n\u003cbr /\u003e\n\n```bash\ngcloud run services update SERVICE --remove-labels LABEL\n```\n\n\u003cbr /\u003e\n\nReplace\n\n- \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with name of your Cloud Run service\n- \u003cvar translate=\"no\"\u003eLABEL\u003c/var\u003e with the name of your label"]]
