This page shows you how to create and manage Tags in your Google Kubernetes Engine (GKE) clusters.
Overview
Tags are key/value pairs that provide a way to conditionally allow or deny policies based on whether a Google Cloud resource has a specific tag. You can attach Tags at the cluster level.
For example, you can use access controls and Tags 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 any 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:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Google Cloud CLI.
- Set up default Google Cloud CLI settings for your project by using one of the following methods:
- Use
gcloud init
, if you want to be walked through setting project defaults. - Use
gcloud config
, to individually set your project ID, zone, and region. -
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
- Follow the instructions to authorize the gcloud CLI to use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone.
- Choose a default Compute Engine region.
- Set your default project ID:
gcloud config set project PROJECT_ID
- Set your default Compute Engine region (for example,
us-central1
):gcloud config set compute/region COMPUTE_REGION
- Set your default Compute Engine zone (for example,
us-central1-c
):gcloud config set compute/zone COMPUTE_ZONE
- Update
gcloud
to the latest version:gcloud components update
gcloud init
gcloud config
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, refer to Required permissions.
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, refer to 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, 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, refer to Tag definitions and identifiers.CLUSTER_LOCATION
: For regional clusters, specify the compute region, such asus-central1
. For zonal clusters, specify the compute zone, such asus-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 Google Cloud console.
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 Edit tags dialog, select the Add Tag bindings option.
Specify the namespaced name of the tag value you want to attach to the cluster. For example,
123456789012/env/dev
. For details about tag identifiers, refer to Tag definitions and identifiers.Add more tag values as required, and then click Save changes.
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, refer to 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"
}
}
List Tags attached to a cluster
You can list the Tags attached to a cluster by using the gcloud CLI, 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 asus-central1
. For zonal clusters, specify the compute zone, such asus-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 Google Cloud console.
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, Google Cloud console, or the Tags API. You must detach tags from all attached resources before you can delete the tag.
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, refer to Tag definitions and identifiers.CLUSTER_LOCATION
: For regional clusters, specify the compute region, such asus-central1
. For zonal clusters, specify the compute zone, such asus-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 Google Cloud console.
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 Edit tags dialog, select the Remove Tag bindings option.
In the Bound Tags section, select the bindings you want to remove.
Click Save changes.
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, refer to Deleting tags to delete the keys and values.