Configure labels for jobs

Cloud Run labels are key-value pairs that are applied toCloud Run jobs. This page shows how to set, modify, anddelete labels on your Cloud Run jobs.

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 aCloud Run job:

Onlyvalid Google Cloud labels can 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:

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run job interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Set or modify labels

You can use Google Cloud CLI, YAML, or Terraform to set a label on aCloud Run job.

gcloud

  1. Toset a label on a new job:

    gcloudrunjobscreateJOB_NAME--imageIMAGE_URL--labelsKEY=VALUE

    Replace the following:

    • JOB_NAME with the name of your job.
    • KEY with the name of your label key.
    • VALUE with the value for the key.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.

  2. To set a label on an existing job:

    gcloudrunjobsupdateJOB_NAME--labelsKEY=VALUE

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

    gcloudrunjobsupdateJOB_NAME--labelsKEY1=VALUE1,KEY2=VALUE2

YAML

  1. If you are creating a new job, skip this step.If you are updating an existing job, download itsYAML configuration:

    gcloudrunjobsdescribeJOB_NAME--formatexport>job.yaml

  2. Update thelabels attributes in two places:

    apiVersion:run.googleapis.com/v1kind:Jobmetadata:labels:LABEL:VALUEspec:template:metadata:labels:LABEL:VALUE

    Replace the following:

    • LABEL with the name of the label.
    • VALUE with the chosen value.

    You can also specify more configuration such as environment variables ormemory limits.

  3. Update the existing job configuration:

    gcloudrunjobsreplacejob.yaml

Terraform

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

Add the following to agoogle_cloud_run_v2_job resource in your Terraform configuration:

resource"google_cloud_run_v2_job""default"{name="JOB_NAME"location="REGION"template{template{containers{image="us-docker.pkg.dev/cloudrun/container/job"}}labels={"LABEL":"VALUE"}}labels={"LABEL":"VALUE"}}

Replace the following:

  • JOB_NAME: the name of your Cloud Run job.
  • REGION: the Google Cloud region. For example,europe-west1.
  • LABEL: the name of the label.
  • VALUE: the chosen value.

List jobs by label

You can list jobs by label using aGoogle Cloud CLI filter:

gcloudrunjobslist--filtermetadata.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 job

To clear all labels from a job:

gcloudrunjobsupdateJOB--clear-labels

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

gcloudrunjobsupdateJOB--remove-labelsLABEL

Replace the following:

  • JOB: the name of your Cloud Run job
  • LABEL: the name of your label

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.