Cluster Labeling on Container Engine

Labels are a lightweight way of grouping together related resources in Google Cloud Platform. For example, you might want to label clusters that you use for production, testing, or development, so that you can track those clusters and associated resources when necessary. Google Cloud Platform also appends any labels you've applied to your resources when providing billing information, so that you can use labels to provide finer-grained information about your project's costs.

Labeling Clusters

In Container Engine, you apply labels at the Cluster level. When you label a cluster, the label you have chosen propagates to all of the cluster's individual resources (such as Compute Engine instances and Persistent Disks).

Label format

Labels are RFC1035-style strings that hold key/value pairs. The format might resemble env:development or type:gpu-enabled. The following restrictions apply:

  • Label keys cannot be empty.
  • The key and value portions of the string each have a 63-character maximum.
  • The key and value must begin with a lowercase letter, and may only contain lowercase letters, dashes, or numbers.
  • The string must not end in a dash.

Creating a cluster with labels

You can add a label to your cluster (and all of its associated resources) at creation time by using the Google Cloud Platform Console. the gcloud command-line tool, or the Container Engine API.

Console

To add labels when creating your cluster with the Google Cloud Platform Console:

  1. On the "Create a container cluster" page, click More.
  2. Click Add label.
  3. Add labels as desired.
  4. Click Create to create your cluster.

gcloud

Using the gcloud command-line tool, run the gcloud beta containers create command with the --labels flag to add labels. For example:

gcloud beta containers create example-cluster --labels=env:dev

API

To include a label when creating your cluster, specify the resourceLabels object inside the cluster object that you provide to projects.zones.clusters.create.

Adding or updating labels for existing clusters

You can add labels or update existing labels on your clusters.

Console

  1. Go to the Cluster Resources page.
  2. Select the checkboxes next to the clusters you want to label.
  3. Click Show info panel to expand the labels column if it isn't already visible.
  4. Update or add new labels as desired.
  5. Save your changes.

gcloud

Using the gcloud command-line tool, use the gcloud containers update command with the --update-labels flag to add or change a label. For example:

gcloud beta containers update example-cluster --update-labels=env:dev

If you provide a label key that already exists, the tool updates the existing key with the new label value. If you provide a new key, the tool adds the new key to the list of labels.

API

To add or update labels, make a POST request to the resourceLabels method of the cluster with the latest fingerprint and a full list of labels to apply.

Similar to metadata and tags, if the cluster has existing labels you want to keep, you must include those labels in the request, along with any new labels you want to add.

For example, the following snippet makes a request to the resourceLabels method for a cluster:

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "env": "test",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Removing a label

Console

  1. Go to the Cluster Resources page.
  2. Select the checkboxes next to the clusters for which you want to remove labels.
  3. Click Show info panel to expand the labels column if it isn't already visible.
  4. Click the X next to all the labels you want to remove.
  5. Save your changes.

gcloud

Using the gcloud command-line tool, run the update command with the --remove-labels flag. Provide a set of label keys to remove. For example:

gcloud beta containers update example-cluster --remove-label=env:dev

API

In the API, make a POST request to the resourceLabels method for the appropriate cluster. Provide the current labelsFingerprint and an empty list of labels to remove all labels, or provide a list of labels you want to keep (omitting the labels you want to remove). For example:

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

Getting a label fingerprint for API requests

When updating or adding labels in the API, you need to provide the latest labels fingerprint with your request, to prevent any conflicts with other requests. This is only required for API requests; the Cloud Platform Console and the gcloud tool does not require a fingerprint.

To get the latest label fingerprint so you can make your request, perform a GET request for the appropriate cluster. For example:

Look for the labelFingerprint property:

Request

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster
200 OK

{

 "name": "mycluster",
 "description": "test-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "env": "test",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Container Engine