Cluster Labeling on Kubernetes Engine

This page provides an overview of cluster labels in Kubernetes Engine.

Overview

Cluster 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 their 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.

About labeling clusters

In Kubernetes Engine, you apply labels at the cluster level. When you label a cluster, the label you have choose propagates to all of the cluster's individual resources (such as nodes and persistent disks).

You can add, update, and remove cluster labels using Google Cloud Platform Console, the gcloud command-line tool, or the Kubernetes Engine API.

Cluster label format

Cluster labels are RFC1035-style strings that hold key-value pairs. The format might resemble env:development or type:gpu-enabled.

The following restrictions apply to cluster labels:

  • Label keys cannot be empty.
  • The key and value portions of the string each have a 63-character limit.
  • 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.

Getting a label fingerprint for API requests

When you update or add cluster labels using the Kubernetes Engine API, you need to provide the latest cluster label fingerprint with your request to prevent any conflicts with other requests.

To get the latest cluster label fingerprint, run a GET request for the appropriate cluster. For example:

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

In the response, look for the labelFingerprint property:

200 OK

{

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

Creating a cluster with labels

Console

To add labels when creating your cluster with Cloud Platform Console, perform the following steps:

  1. Visit the Kubernetes Engine menu in the Google Cloud Platform Console.

    Visit the Kubernetes Engine menu

  2. Click Create cluster.

  3. Configure your cluster as desired. Then, click More.
  4. Click Add label.
  5. Add labels as desired.
  6. Click Create.

gcloud

To add labels when creating your cluster with gcloud, run the following command:

gcloud beta container clusters create [CLUSTER-NAME] --labels=[KEY]=[VALUE]

For example:

gcloud beta container clusters create example-cluster --labels=env=dev

API

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

Adding or updating labels for existing clusters

Console

To add or update labels using Google Cloud Platform Console, perform the following steps:

  1. Visit the Kubernetes Engine menu in the Google Cloud Platform Console.

    Visit the Kubernetes Engine menu

  2. Select the checkboxes beside 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. Click Save.

gcloud

To add or update labels with gcloud, run the following command:

gcloud beta container clusters update [CLUSTER-NAME] --update-labels=[KEY]=[VALUE]

For example:

gcloud beta container clusters 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 cluster's resourceLabels method 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 that you want to add.

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

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 cluster labels

Console

To remove a label using Google Cloud Platform Console, perform the following steps:

  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 container clusters 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="
}

What's next

Monitor your resources on the go

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

Send feedback about...

Kubernetes Engine