Using annotations and labels with Cloud Deploy

You can attach annotations and labels to your Cloud Deploy resources. They're not required.

This document lists the resources to which you can attach labels and annotations, and describes how you can use them and where you can view them.

About annotations and labels

Annotations are key-value pairs of free-form text. You can use them to attach arbitrary information associated with the resource.

You can use labels to organize resources. For example, you can apply logic based on label selection.

As with annotations, labels are key-value pairs. But they must conform to the following limitations:

  • A Cloud Deploy resource can have no more than 64 labels.

  • Keys and values both must be 128 bytes or less.

  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes.

  • Keys must start with a lowercase letter or international character.

  • All characters must use UTF-8 encoding. International characters are allowed.

The --labels flag (for example, on gcloud deploy releases create) can take a list of key-value pairs:

"name=wrench,mass=1.3kg,count=3"

See the Cloud Deploy API documentation for more details.

Adding annotations and labels to Cloud Deploy resources

You can add annotations and labels to the following Cloud Deploy resources:

apiVersion: deploy.cloud.google.com/v1
  kind: DeliveryPipeline
  metadata:
   name:
   annotations:
     key: "value"
   labels:
     key: "value"
  description:
  serialPipeline:
   stages:
   - targetId:
     profiles: []
   - targetId:
     profiles: []

  • Targets

    Add annotations and labels to targets in the target configuration YAML.

    For example, you can include a link to more information about third-party monitoring for your application. However, if the target is shared, remember that it could be used for more than one application, so the link should not be application specific.

  • Releases

    You can add annotations or labels, or both, to a release using the --labels and --annotations flags on the gcloud deploy releases create command. Labels and annotations you add to a release are not carried forward as labels or annotations on resulting rollouts.

    For example, you can use annotations to include a reference to a Git PR, author, or SHA hash of the Git commit containing the changes to be deployed. See Using annotations to track the release's provenance for more details.

  • Rollouts

    You can add annotations and labels to new rollouts by specifying --labels or --annotations on the gcloud deploy releases promote command.

    You can add annotations and labels to the first rollout by specifying --initial-rollout-labels or --initial-rollout-annotations on the gcloud deploy releases create command.

    Some things you can do using annotations on a rollout:

    • Create an annotation containing the URL pointing to test results.
    • Create an annotation with a relevant ticket number from a workflow management system.