Using labels

Learn how to create and use labels in your Cloud Run for Anthos services and revisions.

Labels are key/value pairs that are applied to the service and revisions. When you set a label on a Cloud Run for Anthos service, a new revision with this label is created for this service; the label is not applied to older revisions.

Labels for Cloud Run for Anthos are Kubernetes resource labels, and are not propagated to Google Cloud. To learn more about using labels to analyze cluster resource usage, see Understanding cluster resource usage.

Labels usage rules

Only valid Kubernetes labels are allowed to be used on Cloud Run for Anthos.

Setting or modifying 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 Cloud Console, the gcloud command-line tool, or a YAML file when you deploy a new service or update an existing service and deploy a revision:

Console

  1. Go to Cloud Run for Anthos

  2. Check the checkbox at the left of the service you are setting the label on.

  3. Make sure the Info Panel at the far right is toggled on (Show Info Panel).

  4. Click Labels to display the labels pane.

    Set label

  5. To edit an existing label key value, locate the label and change the Value as desired.

  6. To set a new label on the service, click Add Label and supply the key and the value.

  7. Click Save

Command line

You can use the gcloud command-line tool to set labels for new services or to update existing services:

  • For existing services, update labels by running the gcloud run services update command with one of the following parameters:

    Example:

    gcloud run services update SERVICE --update-labels KEY1=VALUE1,KEY2=VALUE2
    

    Replace:

    • SERVICE with the name of your service.
    • KEY1=VALUE1,KEY2=VALUE2 with a comma separated list of name and value pairs for each label. Specify the label name for each KEY and the value for VALUE. How to specify multiple parameters.
    • Command parameter options

      To specify several sets of key-value pairs, you can specify multiple parameters for readability. Example:
      [...]
      --set-labels "KEY=VALUE1" \
      --set-labels "KEY=VALUE2" \
      --set-labels "KEY=VALUE3"
      
  • For new services, set labels by running the gcloud run deploy command with the --set-labels parameter:

    gcloud run deploy SERVICE --image=IMAGE_URL --set-labels KEY1=VALUE1,KEY2=VALUE2
    

    Replace:

    • IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.
    • SERVICE with the name of your service.
    • KEY1=VALUE1,KEY2=VALUE2 with a comma separated list of name and value pairs for each label. Specify the label name for each KEY and the value for VALUE. How to specify multiple parameters.
    • Command parameter options

      To specify several sets of key-value pairs, you can specify multiple parameters for readability. Example:
      [...]
      --set-labels "KEY=VALUE1" \
      --set-labels "KEY=VALUE2" \
      --set-labels "KEY=VALUE3"
      

YAML

You can download the configuration of an existing service into a YAML file with the gcloud run services describe command by using the --format=export flag. You can then modify that YAML file and deploy those changes with the gcloud beta run services replace command. You must ensure that you modify only the specified attributes.

  1. Download the configuration of your service into a file named service.yaml on local workspace:

    gcloud run services describe SERVICE --format export > service.yaml

    Replace SERVICE with the name of your Cloud Run for Anthos service.

  2. In your local file, update the labels attribute:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
      labels:
        LABEL: 'VALUE'

    Replace

    • SERVICE with the name of your Cloud Run for Anthos service
    • LABEL with the name of the label
    • VALUE with the desired value
  3. Replace the service with its new configuration using the following command:

    gcloud beta run services replace service.yaml

Listing services by label

You can list services by label using a Cloud SDK 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

Deleting a label

You can use the console or the command line delete labels.

Console

  1. Go to Cloud Run for Anthos

  2. Check the checkbox at the left of the service you are deleting the label from.

  3. Make sure the Info Panel at the far right is toggled on (Show Info Panel).

  4. Click Labels to display the labels pane.

  5. Locate the label you want to delete.

  6. Hover your cursor to the right of the Value textbox for the label to display the trash icon, and click the trash icon.

  7. Click Save

Command line

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 for Anthos service
  • LABEL with the name of your label