Creating and Managing Labels

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

What are cluster labels?

A cluster label is a key-value pair that helps you organize your Google Cloud Platform resources, such as clusters. 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 cluster labels

Here are some common use cases for cluster labels:

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

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

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

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

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

Requirements for cluster labels

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

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

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • Set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • Update all gcloud commands to the latest version:
    gcloud components update

Configure gcloud to use the v1beta1 API

To use this feature with gcloud, you must enable the v1beta1 API surface for gcloud, which allows you to run gcloud beta container clusters commands.

To configure the gcloud command-line tool to use the v1beta1 API, run one of the following commands in your shell or terminal window:

export CLOUDSDK_CONTAINER_USE_V1_API_CLIENT=false
or:
gcloud config set container/use_v1_api false

About labeling clusters

In Kubernetes 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 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.

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 GCP Console, perform the following steps:

  1. Visit the Kubernetes Engine menu in GCP 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 the gcloud tool, 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 GCP Console, perform the following steps:

  1. Visit the Kubernetes Engine menu in GCP 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 update labels with the gcloud tool, 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,release=stable

If the cluster has existing labels you want to keep, you must include those labels along with any new labels that you want to add.

API

To 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 GCP Console, perform the following steps:

  1. Visit the Kubernetes Engine menu in GCP Console.

    Visit the Kubernetes Engine menu

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

Read the Kubernetes Engine overview.

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine