Creating and managing cluster labels

This page provides an overview of cluster labels in Google Kubernetes Engine (GKE).

What are cluster labels?

A cluster label is a key-value pair that helps you organize your Google Cloud 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 billed charges by label.

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. For more information, see the Tags overview.

Common uses of cluster labels

We do not recommend creating large numbers of unique labels, such as for timestamps or individual values for every API call. 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.

  • 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.

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

Automatically applied labels

After clusters are created, GKE automatically applies several labels to the cluster resources. For example, GKE applies labels to Compute Engine instances, persistent disks, and accelerators (TPU). Automatically applied labels have a special goog-gke- prefix.

The following goog-gke- labels are automatically applied to GKE resources. Any modifications you perform for the reserved goog-gke- labels from either the Compute Engine level or the GKE cluster level will be reconciled automatically. For this reason, editing or deleting those reserved labels is not recommended.

Label Applied Resources
goog-gke-node GKE nodes
goog-gke-volume Persistent disks attached to GKE nodes
goog-gke-tpu Cloud TPU on GKE

Label propagation

In GKE, 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).

Any labels you apply to your clusters propagate through a background process that runs hourly. It can take up to one hour for a label to appear on all resources associated with a given cluster. In addition, labels only propagate to Compute Engine instances and zonal Persistent Disks (not including regional Persistent Disks). Other resources such as workloads, forwarding rules and IPs are not labeled.

Before you begin

Before you start, make sure you have performed the following tasks:

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

  1. Run gcloud init and follow the directions:

    gcloud init

    If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

    gcloud init --console-only
  2. Follow the instructions to authorize gcloud to use your Google Cloud account.
  3. Create a new configuration or select an existing one.
  4. Choose a Google Cloud project.
  5. Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.

Using gcloud config

  • Set your default project ID:
    gcloud config set project PROJECT_ID
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone COMPUTE_ZONE
  • If you are working with Autopilot or regional clusters, set your default compute region:
    gcloud config set compute/region COMPUTE_REGION
  • Update gcloud to the latest version:
    gcloud components update

Getting a label fingerprint for API requests

When you update or add cluster labels using the GKE 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

You can create a cluster with labels by using the gcloud tool, the Google Cloud Console, or the GKE API.

gcloud

Run the following command:

gcloud container clusters create CLUSTER_NAME --labels KEY=VALUE

Replace the following:

  • CLUSTER_NAME: the name of your cluster.
  • KEY: the key for the label's key-value pair.
  • VALUE: the value for the label's key-value pair.

For example:

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

Console

To add labels when creating your cluster:

  1. Go to the Google Kubernetes Engine page in the Cloud Console.

    Go to Google Kubernetes Engine

  2. Click Create.

  3. Configure your cluster as desired.

  4. From the navigation pane, under Cluster, click Metadata.

  5. Click Add label.

  6. Add labels as desired.

  7. Click Create.

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

gcloud

To update labels with the gcloud tool, run the following command:

gcloud container clusters update CLUSTER_NAME \
    [--region COMPUTE_REGION | --zone COMPUTE_ZONE] \
    --update-labels KEY=VALUE

Replace the following:

  • CLUSTER_NAME: the name of your cluster.
  • COMPUTE_REGION: if your cluster is regional, specify the Compute Engine region for the cluster.
  • COMPUTE_ZONE: if your cluster is zonal, specify the Compute Engine zone for the cluster.
  • KEY: the key for the label's key-value pair.
  • VALUE: the value for the label's key-value pair.

For example:

gcloud container clusters update example-cluster --zone us-west1-a \
    --update-labels env=dev,release=stable

The label update will overwrite any pre-existing labels. 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.

Console

To add or update labels:

  1. Go to the Google Kubernetes Engine page in Cloud Console.

    Go to Google Kubernetes Engine

  2. In the cluster list, select one or more clusters you want to modify.

  3. Click Show Info Panel if it isn't already visible.

  4. Add or update labels as desired.

  5. Click Save.

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

gcloud

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

gcloud container clusters update CLUSTER_NAME --remove-labels KEY

Replace the following:

  • CLUSTER_NAME: the name of your cluster.
  • KEY: the key of the label to remove.

For example:

gcloud container clusters update example-cluster --remove-labels env

Console

To remove labels:

  1. Go to the Google Kubernetes Engine page in Cloud Console.

    Go to Google Kubernetes Engine

  2. In the cluster list, select one or more clusters you want to modify.

  3. Click Show Info Panel if it isn't already visible.

  4. Click Delete item next to the Value field for the labels you want to delete.

  5. Click Save.

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 GKE overview.