Create and manage Tags in GKE

Autopilot Standard

This page shows you how to create and manage Tags in your Google Kubernetes Engine (GKE) clusters.

Overview

A tag is a key-value pair that can attach to a resource within Google Cloud. You can use tags to conditionally allow or deny policies based on whether a resource has a specific tag.

As a platform administrator, you can use access controls and Tags to conditionally grant Identity and Access Management (IAM) roles based on whether a cluster has a specific tag. For example, you can configure GKE to automatically grant Identity and Access Management roles to users who are contractors so that they can access specific clusters that are normally available only to full-time employees.

After creating a tag, you can attach the tag to a Google Cloud resource as a key-value pair using a tag binding. For each key, you can attach one value to a resource. For example, if you attached env:dev to a GKE cluster, you can't also attach env:prod or env:test. You can attach up to 50 Tags to each resource.

In GKE, there are several methods to annotate your resources, as outlined in the following table:

Annotation type	Tags	GKE cluster labels	Kubernetes labels
Level	GKE cluster	GKE cluster	Kubernetes object
Purpose	Conditionally allow or deny policies based on the tag.	Organize GKE resources to track usage and billing.	Associate cluster components and resources with one another and manage resource lifecycles.
Example	Automatically grant users who are contractors access to specific clusters that are normally available only to full-time employees.	Differentiate between clusters owned by specific cost centers or teams in your organization.	Require that workloads are scheduled on nodes with specific labels.
Learn more	Tags overview	Cluster labels	Kubernetes labels and selectors

Before you begin

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

Enable the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Ensure that you have the following IAM roles:
- roles/resourcemanager.tagAdmin
- roles/resourcemanager.tagUser
For information on the permissions granted by these roles, see Required permissions.
Ensure that you have a GKE cluster running.

Create tag keys and values

Before you can attach a tag to your GKE resources, you need to create the tag and configure its values. To create tag keys and values, see Creating a tag and Adding tag values.

Attach Tags to a cluster

You can attach Tags to an existing cluster if you have the correct permissions by using the Google Cloud CLI, the Google Cloud console, or the Tags API.

gcloud

To create a tag binding to attach a tag to a cluster, run the following command:

gcloud alpha resource-manager tags bindings create \
    --tag-value=TAG_VALUE_ID \
    --parent=RESOURCE_ID \
    --location=CLUSTER_LOCATION

Replace the following:

TAG_VALUE_ID: The permanent ID or namespaced name of the tag value to attach. For example, tagValues/4567890123. For details about tag identifiers, see Tag definitions and identifiers.
CLUSTER_LOCATION: For regional clusters, specify the compute region, such as us-central1. For zonal clusters, specify the compute zone, such as us-central1-a.
RESOURCE_ID: The full resource name of your cluster, such as //container.googleapis.com/projects/PROJECT_ID/locations/CLUSTER_LOCATION/clusters/CLUSTER_NAME.

In the resource ID:
- PROJECT_ID: Your Google Cloud project ID.
- CLUSTER_NAME: The name of your cluster.

Console

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
In the Metadata section, next to Tags, click Edit tags.
If your organization doesn't appear in the Tags panel, click Select scope. Select your organization and click Open.
In the Tags panel, select Add tag.
Select the key for the tag you want to attach from the list. You can filter the list by typing keywords.
Select the value for the tag you want to attach from the list. You can filter the list by typing keywords.
Click Save.
In the Confirm dialog, click Confirm to attach the tag.

A notification confirms that your tags updated.

API

To attach a tag to a resource, you must first create a JSON representation of a tag binding that includes the permanent IDs of the tag value and the resource. For more information about the format of a tag binding, see the TagBinding reference.

Use the tagBindings.create method with the regional or zonal endpoint where your cluster is located.

POST https://LOCATION-cloudresourcemanager.googleapis.com/v3/tagBindings

Replace LOCATION with the region or zone where your cluster is located, such as us-central1.

JSON request body:

{
  "parent": "RESOURCE_ID",
  "tagValue": "TAG_VALUE_ID"
}

Replace the following:

RESOURCE_ID: The full resource name of your cluster, such as //container.googleapis.com/projects/PROJECT_ID/locations/CLUSTER_LOCATION/clusters/CLUSTER_NAME.

In the resource ID:
- PROJECT_ID: Your Google Cloud project ID.
- CLUSTER_NAME: The name of your cluster.
TAG_VALUE_ID: The permanent ID or namespaced name of the tag value to attach. For example, tagValues/4567890123. For details about tag identifiers, see Tag definitions and identifiers.

The output is similar to the following:

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.TagBinding",
    "name": "tagBindings///container.googleapis.com/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME/tagValues/TAG_VALUE_ID",
    "parent": "//container.googleapis.com/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME",
    "tagValue": "TAG_VALUE_ID"
  }
}

You can list the Tags attached to a cluster by using the gcloud CLI, the Google Cloud console, or the Tags API.

gcloud

To get a list of tag bindings attached to a cluster, run the following command:

gcloud alpha resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=CLUSTER_LOCATION

Replace the following:

CLUSTER_LOCATION: For regional clusters, specify the compute region, such as us-central1. For zonal clusters, specify the compute zone, such as us-central1-a.
RESOURCE_ID: The full resource name of your cluster, such as //container.googleapis.com/projects/PROJECT_ID/locations/CLUSTER_LOCATION/clusters/CLUSTER_NAME.

In the resource ID:
- PROJECT_ID: Your Google Cloud project ID.
- CLUSTER_NAME: The name of your cluster.

Console

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to view.
In the Metadata section, next to Tags, look for the currently attached tag values.

API

To get a list of tag bindings for a cluster, use the tagBindings.list method with the regional or zonal endpoint where your cluster is located.

GET https://LOCATION-cloudresourcemanager.googleapis.com/v3/tagBindings

JSON request body:

{
  "parent": RESOURCE_ID,
}

Replace the following:

RESOURCE_ID: The full resource name of your cluster, such as //container.googleapis.com/projects/PROJECT_ID/locations/CLUSTER_LOCATION/clusters/CLUSTER_NAME.

In the resource ID:
- PROJECT_ID: Your Google Cloud project ID.
- CLUSTER_NAME: The name of your cluster.

The output is similar to the following:

"tagBindings": [
  {
    "name": "tagBindings/%2F%2Fcontainer.googleapis.com%2Fprojects%2Ftags-bugbash-project%2Flocations%2Fus-central1%2Fclusters%2Ftestcluster/tagValues/758072120217",
    "parent": "//container.googleapis.com/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME",
    "tagValue": "TAG_VALUE_ID"
  }
]

Detach tags from a cluster

You can detach a tag from a cluster by deleting the tag binding resource attached to the cluster by using the gcloud CLI, the Google Cloud console, or the Tags API. If you need to delete a tag, you must first detach from all attached resources.

gcloud

To detach a tag binding attached to a cluster, run the following command:

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAG_VALUE_ID \
    --parent=RESOURCE_ID \
    --location=CLUSTER_LOCATION

Replace the following:

TAG_VALUE_ID: The permanent ID or namespaced name of the tag value to detach. For example, tagValues/4567890123. For details about tag identifiers, see Tag definitions and identifiers.
CLUSTER_LOCATION: For regional clusters, specify the compute region, such as us-central1. For zonal clusters, specify the compute zone, such as us-central1-a.
RESOURCE_ID: The full resource name of your cluster, such as //container.googleapis.com/projects/PROJECT_ID/locations/CLUSTER_LOCATION/clusters/CLUSTER_NAME.

In the resource ID:
- PROJECT_ID: Your Google Cloud project ID.
- CLUSTER_NAME: The name of your cluster.

Console

Go to the Google Kubernetes Engine page in the Google Cloud console.

Go to Google Kubernetes Engine
In the cluster list, click the name of the cluster you want to modify.
In the Metadata section, next to Tags, click Edit tags.
In the Tags panel, next to the tag you want to detach, click Delete item.
Click Save.
In the Confirm dialog, click Confirm to detach the tag.

A notification confirms that your tags updated.

API

To delete tag bindings for a cluster, use the tagBindings.delete method with the regional or zonal endpoint where your cluster is located.

DELETE https://LOCATION-cloudresourcemanager.googleapis.com/v3/TAG_BINDING_NAME

Replace TAG_BINDING_NAME with the full resource name of the tagBinding object you want to detach. For example, tagBindings/container.googleapis.com/projects/PROJECT_ID/locations/LOCATION/tagValues/TAG_VALUE_ID.

Delete tag keys and tag values

Before you delete tag keys and values, ensure that the tags are detached from all resources. Then, see Deleting tags to delete the keys and values.

Identity and Access Management conditions and tags

You can use tags and IAM conditions to conditionally grant role bindings to users in your project hierarchy. When you change or delete the tag attached to a cluster, GKE can remove user access to that cluster if an IAM policy with conditional role bindings has been applied.

Authorization to list and create GKE clusters is checked at the project level, not at the individual cluster level. If you use conditional IAM role bindings with cluster-level tags to restrict access to specific clusters, those users might experience errors when attempting to list or create clusters in the project. To avoid these errors, attach a tag to the parent project and use a conditional role binding to grant the list or create access. For information about roles and permissions, see the IAM roles reference.

For more information about conditional access grants in IAM, see Identity and Access Management conditions and tags.

What's next

Learn how to set an organization policy with Tags.
Learn more about how to manage tags and attach tags to resources.
See the other services that support tags.
Learn how to use tags with IAM.

Create and manage Tags in GKE

Overview

Before you begin

Create tag keys and values

Attach Tags to a cluster

gcloud

Console

API

List Tags attached to a cluster

gcloud

Console

API

Detach tags from a cluster

gcloud

Console

API

Delete tag keys and tag values

Identity and Access Management conditions and tags

What's next