Configure labels

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 service revision with this label is created for this service; the label is not applied to older revisions.

Possible uses include:

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

Labels usage rules

The following rule applies to the use of labels set on a Cloud Run service:

Only valid Google Cloud labels are allowed to be used on Cloud Run.

Required roles

To get the permissions that you need to configure and deploy Cloud Run services, ask your administrator to grant you the following IAM roles:

Cloud Run Developer (roles/run.developer) on the Cloud Run service
Service Account User (roles/iam.serviceAccountUser) on the service identity

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 service 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 console, the gcloud command line, or a YAML file when you deploy a new revision.

Console

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Check the checkbox at the left of the service you are setting the label on.
Make sure the Info Panel at the far right is toggled on (Show Info Panel).
Click Labels to display the labels pane.
To edit an existing label key value, locate the label and change the Value as desired.
To set a new label on the service, click Add Label and supply the key and the value.
Click Save

gcloud

You can update labels for a service using the command:

gcloud run services update SERVICE --update-labels KEY=VALUE

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.

Replace

SERVICE with name of your Cloud Run service
KEY with the name of your label key
VALUE with the value for the key

You can also set labels during deployment:

gcloud run deploy SERVICE --image IMAGE --labels KEY=VALUE

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

YAML

If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Update the labels attributes in two places:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    LABEL: VALUE
spec:
  template:
    metadata:
      labels:
        LABEL: VALUE
      name: REVISION
```
Replace
- SERVICE with the name of your Cloud Run service
- LABEL with the name of the label
- VALUE with the desired value
- 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:
```
gcloud run services replace service.yaml
```

Terraform

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

The following snippet adds two labels, foo (whose value is bar) and baz (whose value is quux), to your Cloud Run instance, using a google_cloud_run_v2_service resource in your Terraform configuration.

Adding the labels under template as shown 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.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-labels"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    # Labels
    labels = {
      foo : "bar"
      baz : "quux"
    }
  }
}

Replace the

name property with the name of your service.
location property with the location used for your service.
image property with your container image.
foo and baz with your own label names.
bar and quux with your own label values.

List services by label

You can list services by label using a Google Cloud CLI filter:

  gcloud run services list --filter metadata.labels.LABEL=VALUE

Replace:

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

Delete a label on a service

You can use the console or the command line delete labels on a service.

Console

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Check the checkbox at the left of the service you are deleting the label from.
Make sure the Info Panel at the far right is toggled on (Show Info Panel).
Click Labels to display the labels pane.
Locate the label you want to delete.
Hover your cursor to the right of the Value textbox for the label to display the trash icon, and click the trash icon.
Click Save

gcloud

To clear all labels from a service:

gcloud run services update SERVICE --clear-labels

To delete specific labels from a service, supply a comma delimited list of keys:

gcloud run services update SERVICE --remove-labels LABEL

Replace

SERVICE with name of your Cloud Run service
LABEL with the name of your label