Manage GKE resources using Tags

This page shows you how to use Tags to manage your Google Kubernetes Engine (GKE) clusters and conditionally apply Identity and Access Management policies to nodes.

Overview

Tags are key-value pairs that let you annotate and manage your Google Cloud resources at the organization or project level. You can use Tags to organize your resources and to conditionally apply policies like firewalls or IAM policies. Tags support IAM access control, which lets you define who can attach, create, update, or delete Tags.

Use cases for Tags in GKE

You might use Tags in GKE for situations like the following:

  • Conditionally apply network firewall policies to specific nodes. For example, deny ingress traffic from the public internet to all nodes of a cluster in staging or testing environments. For instructions, see Selectively enforce network firewall policies in GKE.
  • Conditionally grant IAM roles based on Tags. For example, automatically grant contractors access to specific environments that would normally only be available to full-time employees. For instructions, see the rest of this document.
  • Audit and analyze billing information based on applied Tags at the project or organization level.

How it works

For network firewall policy enforcement specifically, you create a tag and explicitly designate the tag for firewall use. For all other purposes, you create a tag without setting a firewall designation.

After creating the tag, you attach the tag to your GKE resources as a key-value pair. For network firewall policies, you use the GKE API, while for all other purposes you use the Tags API.

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 non-firewall Tags and up to five firewall Tags to each resource.

Resource annotation methods in GKE

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

Annotation type Description Example
Tags (non-firewall)
  • Apply to cluster resource by using the Tags API
  • Organize resources to track usage and billing
  • Conditionally apply IAM policies
  • Control access to specific Tags with IAM

To learn more, see Tags overview.

 Conditionally grant IAM roles to control access to resources that have specific Tags
Tags (firewall)
  • Apply to cluster or node pool using GKE API
  • Conditionally apply Cloud Next Generation Firewall network firewall policies.
  • Control access to specific Tags with IAM
  • GKE attaches the key-value pairs to the underlying Compute Engine VMs.

To learn more, see Selectively apply network firewall policies in GKE.

 Automatically deny ingress traffic from public internet to all staging or testing environments
Network tags
  • Apply to cluster or node pool using GKE API
  • Simple strings with no IAM access control
  • Use to conditionally apply VPC firewall rules
  • GKE attaches the key-value pairs to the underlying Compute Engine VMs

To learn more, see Use network tags to apply firewall rules to nodes.

 Automatically deny ingress traffic from public internet to all staging or testing environments
GKE cluster labels
  • Apply to cluster or node pool using GKE API
  • Organize resources to track usage and billing

To learn more, see Cluster labels.

 Differentiate between clusters owned by specific cost centers or teams in your organization.
Kubernetes labels
  • Apply to Kubernetes API objects
  • Associate cluster components and resources with one another and manage resource lifecycles.

To learn more, see Kubernetes labels and selectors.

 Require that workloads are scheduled on nodes with specific labels.

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.

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, the Tags API, or Terraform.

gcloud

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

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: the Compute Engine location. For zonal clusters, specify the compute zone.

  • 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

Before you can attach a tag to your GKE resources using the Google Cloud console, you must create the tag and configure its values. To create tag keys and values, see Creating a tag and Adding tag values.

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

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. In the Metadata section, next to Tags, click Edit tags.

  4. If your organization doesn't appear in the Tags panel, click Select scope. Select your organization and click Open.

  5. In the Tags panel, select Add tag.

  6. Select the key for the tag you want to attach from the list. You can filter the list by typing keywords.

  7. Select the value for the tag you want to attach from the list. You can filter the list by typing keywords.

  8. Click Save.

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

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"
  }
}

Terraform

To create a tag, configure its values, and attach a tag to a resource using Terraform, refer to the following example:

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-tag"
  location = "us-central1"

  enable_autopilot = true

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

data "google_project" "default" {}

resource "google_tags_tag_key" "default" {
  parent      = "projects/${data.google_project.default.project_id}"
  short_name  = "env"
  description = "Environment tag key"
}

resource "google_tags_tag_value" "default" {
  parent      = "tagKeys/${google_tags_tag_key.default.name}"
  short_name  = "dev"
  description = "Development environment tag value."
}

resource "google_tags_location_tag_binding" "default" {
  parent    = "//container.googleapis.com/${google_container_cluster.default.id}"
  location  = google_container_cluster.default.location
  tag_value = "tagValues/${google_tags_tag_value.default.name}"
}

To learn more about using Terraform, see Terraform support for GKE.

List Tags attached to a cluster

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. For zonal clusters, specify the compute zone.

  • 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

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

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to view.

  3. 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%2LOCATION%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. For zonal clusters, specify the compute zone.

  • 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

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

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. In the Metadata section, next to Tags, click Edit tags.

  4. In the Tags panel, next to the tag you want to detach, click Delete item.

  5. Click Save.

  6. 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 allow 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