Adding Labels to a Deployment

Labels are a lightweight way to organize deployments that are related or associated with each other. For example, a common practice is to label deployments that are intended for production, staging, or development separately, so you can easily search for deployments that belong to each stage when necessary.

What are labels?

A label is a key-value pair that you can assign to Google Cloud deployments. They help you organize these resources and manage your costs at scale, with the granularity you need. You can attach a label to each resource, then filter the resources based on their labels. Information about labels is forwarded to the billing system that lets you break down your billed charges by label. With built-in billing reports, you can filter and group costs by resource labels. You can also use labels to query billing data exports.

Requirements for labels

The labels applied to a resource must meet the following requirements:

  • Each resource can have up to 64 labels.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters, and cannot be empty. Values can be empty, and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed. Keys must start with a lowercase letter or international character.
  • The key portion of a label must be unique within a single resource. However, you can use the same key with multiple resources.

These limits apply to the key and value for each label, and to the individual Google Cloud resources that have labels. There is no limit on how many labels you can apply across all resources within a project.

Common uses of labels

Here are some common use cases for labels:

  • Team or cost center labels: Add labels based on team or cost center to distinguish deployments owned by different teams (for example, team:research and team:analytics). You can use this type of label for cost accounting or budgeting.

  • Component labels: For example, component:redis, component:frontend, component:ingest, and component:dashboard.

  • Environment or stage labels: For example, environment:production and environment:test.

  • State labels: For example, state:active, state:readytodelete, and state:archive.

  • Ownership labels: Used to identify the teams that are responsible for operations, for example: team:shopping-cart.

We don't recommend creating large numbers of unique labels, such as for timestamps or individual values for every API call. The problem with this approach is that when the values change frequently or with keys that clutter the catalog, this makes it difficult to effectively filter and report on resources.

Labels and tags

Labels can be used as queryable annotations for resources, but can't be used to set conditions on policies. Tags provide a way to conditionally allow or deny policies based on whether a resource has a specific tag, by providing fine-grained control over policies. For more information, see the Tags overview.

Creating a deployment with labels

When creating a deployment, you can add labels by providing one or more key value pairs as labels when you create your deployment. If you have an existing deployment, you can update the deployment to add new labels or change existing labels.

You must use the gcloud CLI or the API to create a deployment with labels.

gcloud

In gcloud, add labels to your deployment by providing the --labels flag, followed by a comma-separated list of key value pairs. For example, the following command adds two labels to the deployment, environment=production and storage=media:

gcloud deployment-manager deployments create example-deployment --config example-config.yaml \
    --labels environment=production,storage=media

To see the labels applied to the deployment, get a description of the deployment:

gcloud deployment-manager deployments describe example-deployment
---
fingerprint: 0p03t0z31PQLOrGH8KdhWQ==
id: '2204841443843636456'
insertTime: '2017-04-18T09:42:47.323-07:00'
labels:
- key: environment
  value: production
- key: storage
  value: media
manifest: manifest-1492533767362
name: example-deployment
operation:
  endTime: '2017-04-18T09:43:04.581-07:00'
  name: operation-1492533767010-54d7398ff76d1-7930b926-f64e72ae
  operationType: insert
  progress: 100
  startTime: '2017-04-18T09:42:48.034-07:00'
  status: DONE
  user:user@example.com

API

In the API, follow the instructions to create your deployment and include the new labels property in your request body. For example:

{
  "name": "example-deployment",
  "target": {
    "config": {
      "content": "..."
      },
   }
  "labels": [
  {
    "key": "environment",
    "value": "production"
  },
  {
    "key": "storage",
    "value": "media"
  }
 ]
}

Removing labels

Console

  1. Go to the Deployments page in the Google Cloud console.

    Go to the Deployments page

  2. If prompted, select your project and click Continue.

  3. Check the box next to the deployment that you want to remove labels from. A side panel appears.

  4. Click X next to each label you want to remove.

  5. Save your changes.

gcloud

In gcloud, remove labels by using the deployments update command and supplying the --remove-labels flag, followed by a comma-separated list of label keys to remove.

For example, the following removes a label with the environment key:

gcloud deployment-manager deployments update example-deployment --remove-labels environment

API

In the API, follow the instructions to update your deployment and include an update to your deployment that does not contain the labels property in your request body, effectively removing labels.

Adding or updating labels

You can add new labels or update labels on existing deployments.

Console

  1. Go to the Deployments page in the Google Cloud console.

    Go to the Deployments page

  2. If prompted, select your project and click Continue.

  3. Check the box next to the deployment you want to update labels from. A side panel opens.

  4. To change label values, update the appropriate label entries. If you want to change the label key, you will need to delete the label and add it again with the new key.

  5. Save your changes.

gcloud

In gcloud, update or add new labels by using the deployments update command and supplying the --update-labels flag, followed by a comma-separated list of the updated labels:

For example, the following updates the environment label:

gcloud deployment-manager deployments update example-deployment --update-labels environment=production

API

In the API, follow the instructions to update your deployment and in your request body, omit the labels property, which removes labels from the deployment.

Adding labels during deployment previews

Before you create a deployment, you can preview the deployment. As part of the preview, you can assign labels to the previewed deployment. For example:

gcloud deployment-manager deployments create example-deployment --config example-config.yaml \
    --labels environment=production --preview

To change labels during preview, you must update the preview with the new labels. To learn more about previews, read the Previewing a Configuration documentation.

Filtering searches using labels

You can search your resources and filter results by labels.

Console

  1. Go to the Deployments page in the Google Cloud console.

    Go to the Deployments page

  2. If prompted, select your project and click Continue.

  3. In the search bar, start typing labels. and the search bar will automatically list labels that you can filter on.

gcloud

In gcloud, make a list request and use the --filter flag. To filter on labels, use the syntax labels.[KEY]=[VALUE]. For example, if you wanted to filter on a label with environment as the key and production as the value, you can run this command:

gcloud deployment-manager deployments list --filter labels.environment=production

For complete documentation about the filter syntax in the gcloud CLI, see the gcloud topic filters documentation.

API

In the API, make a list request with a URL encoded filter query parameter. For example, to filter based on a label key environment being equal to value production, make the following GET request:

GET https://www.googleapis.com/deploymentmanager/v2/deployments/list?filter=labels.environment+eq+production

For more information, read the filter documentation in the API reference.

What's next