Cloud Run labels are key/value pairs that are applied to Cloud Run jobs. This page shows how to set, modify, and delete labels on your Cloud Run jobs.
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 job:
Only valid Google Cloud labels are allowed to be used on Cloud Run.
Required roles
To get the permissions that you need to configure Cloud Run jobs, ask your administrator to grant you the following IAM roles:
-
Cloud Run Developer (
roles/run.developer
) on the Cloud Run job -
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 job 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
You can use Google Cloud CLI or YAML to set a label on a Cloud Run job.
gcloud
To set a label on a new job:
gcloud run jobs create JOB_NAME --image IMAGE_URL --labels KEY=VALUE
Replace
- JOB_NAME with the name of your job.
- KEY with the name of your label key
- VALUE with the value for the key
- Replace IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/job:latest
.
To set a label on an existing job:
gcloud run jobs update JOB_NAME --labels KEY=VALUE
To create more than one label, supply a comma delimited list of key/value pairs.
gcloud run jobs update JOB_NAME --labels KEY1=VALUE1,KEY2=VALUE2
YAML
If you are creating a new job, skip this step. If you are updating an existing job, download its YAML configuration:
gcloud run jobs describe JOB_NAME --format export > job.yaml
Update the
labels
attributes in two places:apiVersion: run.googleapis.com/v1 kind: Job metadata: labels: LABEL: VALUE spec: template: metadata: labels: LABEL: VALUE
Replace
- LABEL with the name of the label
- VALUE with the desired value
You can also specify more configuration such as environment variables or memory limits.
Update the existing job configuration:
gcloud run jobs replace job.yaml
List jobs by label
You can list jobs by label using a Google Cloud CLI filter:
gcloud run jobs 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 job
To clear all labels from a job:
gcloud run jobs update JOB --clear-labels
To delete specific labels from a service, supply a comma delimited list of keys:
gcloud run jobs update JOB --remove-labels LABEL
Replace
- JOB with name of your Cloud Run job
- LABEL with the name of your label