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 helps you organize your Google Cloud Platform deployments. 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, so you can break down your billing charges by label.

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.

  • Owner or contact labels: Add labels based on the owner or a primary contact for deployments.

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

Requirements for labels

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

  • Each resource can have multiple labels, up to a maximum of 64.
  • 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.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

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 tool 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, devserver=backend and storage=media:

gcloud deployment-manager deployments create example-deployment --config example-config.yaml \
    --labels devserver=backend,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: devserver
  value: backend
- 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": "devserver",
    "value": "backend"
  },
  {
    "key": "storage",
    "value": "media"
  }
 ]
}

Removing labels

Console

  1. Go to the Deployments page in the Google Cloud Platform 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 devserver key:

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

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 Platform 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 devserver label:

gcloud deployment-manager deployments update example-deployment --update-labels devserver=frontend

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 devserver=backend --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 Platform 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 env as the key and dev as the value, you can run this command:

gcloud deployment-manager deployments list --filter labels.env=dev

For complete documentation about the filter syntax in the gcloud tool, 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 env being equal to value dev, make the following GET request:

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

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

What's next

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Cloud Deployment Manager Documentation