This page provides an overview of cluster labels in 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 billing charges by label.
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
andteam:analytics
). You can use this type of label for cost accounting or budgeting.Component cluster labels: For example,
component:redis
,component:frontend
,component:ingest
, andcomponent:dashboard
.Environment or stage cluster labels: For example,
environment:production
andenvironment:test
.State cluster labels: For example,
state:active
,state:readytodelete
, andstate: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 enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
- 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 regional clusters, set your default compute region:
gcloud config set compute/region [COMPUTE_REGION]
- Update
gcloud
to the latest version:gcloud components update
About labeling clusters
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).
You can add, update, and remove cluster labels using Google Cloud Console, the
gcloud
command-line tool, or the GKE API.
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
gcloud
To add labels when creating your cluster with the gcloud
tool, run the following
command:
gcloud container clusters create [CLUSTER_NAME] --labels [KEY]=[VALUE]
For example:
gcloud container clusters create example-cluster --labels env=dev
Console
To add labels when creating your cluster with Cloud Console, perform the following steps:
Visit the Google Kubernetes Engine menu in Cloud Console.
Click Create cluster.
Configure your cluster as desired. Then, click Advanced options.
Click Add label.
Add labels as desired.
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] --update-labels [KEY]=[VALUE]
For example:
gcloud container clusters update example-cluster --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 using Cloud Console, perform the following steps:
Visit the Google Kubernetes Engine menu in Cloud Console.
To add labels to a single cluster, click its Edit button, which looks like a pencil.
- Click Add labels and add one or more labels.
- Click Save.
To add labels to multiple clusters at once:
- Select the checkboxe the clusters you want to label.
- Click Show info panel to expand the labels column if it isn't already visible.
- Update or add new labels as desired.
- 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
command-line tool, run the update
command with the
--remove-labels
flag. Provide a set of label keys to remove. For example:
gcloud container clusters update example-cluster --remove-labels env
Console
To remove a label using Cloud Console, perform the following steps:
Visit the Google Kubernetes Engine menu in Cloud Console.
To remove labels from a single cluster, click its Edit button, which looks like a pencil.
- Click the X next to any label to remove it.
- Click Save.
To remove labels from multiple clusters at once:
- Select the checkboxes next to the clusters for which you want to remove labels.
- Click Show info panel to expand the labels column if it isn't already visible.
- Click the X next to all the labels you want to remove.
- 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=" }