Manage tags for resources

This guide describes how to create and manage tags for Compute Engine resources. A tag is a key-value pair that can be attached to a Google Cloud Platform resource. Tags are used for several purposes, including:

  • Conditionally allow or deny policies based on whether a resource has a specific tag.
  • Define sources and targets in global network firewall policies and regional network firewall policies.
  • Organizing resources in a logical manner.

After creating a tag and granting appropriate access to both the tag and the resource, you can attach the tag as a key-value pair. You can attach exactly one value to a resource for a given key. For example, if you attach the environment: development tag, then you cannot attach the environment: production or environment: test tags. Each resource can have a maximum of 50 key-value pairs attached.

To attach tags to resources, you must create a TagBinding resource that links the tag value to the Google Cloud resource. For more information on tags and how they work, review the Tags overview.

Before you begin

  • Read the Tags overview on the Resource Manager documentation.
  • Read the Creating and managing tags on the Resource Manager documentation.
  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Permissions

To manage tags for Compute Engine resources, users and service accounts should be granted the tagUser role. For more information on the tagUser role, see Required permissions.

Supported resources

The following resources support tagging only after resource creation:

  • Virtual machine (VM) instance
  • Disk
  • Managed Instance Group
  • Image
  • Snapshot
  • Most networking resources such as Network, Subnetwork, Firewall, and HealthCheck resources.

The following resources also support tagging during resource creation:

  • VM instance
  • Disk

Adding tags to a resource

Existing tags can be attached to certain resources after the resource has been created, using the following instructions.

Console

Depending on the resource type, the exact steps might be a bit different. For example, the following steps attach a tag to a VM:

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select your project and click Continue.

  3. In the Name column, click the name of the VM for which you want to add tags.

  4. From the VM instance details page, complete the following steps:

    1. Click Edit.
    2. In the Basic section, click Manage Tags and add the tags that you want for the instance.
    3. Click Save.

gcloud

To review detailed instructions on how to use these flags, read Attach a tag to a resource in the Resource Manager documentation.

For example, the following command attaches a tag to a VM:

gcloud resource-manager tags bindings create \
    --location LOCATION_NAME \
    --tag-value=tagValues/TAGVALUE_ID \
    --parent=//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID

Replace the following:

  • LOCATION_NAME: the region of the target resource, such as us-central1
  • TAGVALUE_ID: the numeric ID of the Tag value
  • PROJECT_NUMBER: the numeric ID your project
  • ZONE: the zone name such as us-central1-a
  • VM_ID: the numeric ID of the VM instance

API

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

To attach the tag to a zonal resource, such as a VM instance, use the tagBindings.create method with the regional endpoint where your resource is located. For example:

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

The request body can be one of:

{
  "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID",
  "tagValue": "tagValue/TAGVALUE_ID"
}

Or the following:

{
  "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID",
  "tagValueNamespacedName": TAGVALUE_NAMESPACED_NAME
}

Replace the following:

  • LOCATION: the location to which the target resource belongs
  • PROJECT_NUMBER: the numeric ID your project
  • ZONE: the zone name such as us-central1-a
  • VM_ID: the numeric ID of the VM
  • TAGVALUE_ID: the permanent ID of the tag value that is attached; for example: 4567890123
  • TAGVALUE_NAMESPACED_NAME is the namespaced name of the tag value that is attached and is of the format: parentNamespace/tagKeyShortName/tagValueShortName

Adding tags to a resource during resource creation

In certain scenarios, you might want to tag resources during resource creation, rather than after the resource is created. For example, you might want to apply firewall tags for network policies when you create the Cloud Next Generation Firewall resource.

Console

Depending on the resource type, the exact steps might be a bit different. The following steps are for a VM:

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select your project and click Continue.

  3. Click Create instance.

  4. Click Manage Tags and Labels.

  5. Click Add Tags.

  6. Follow the instructions in the side panel to select the tags to add to the instance.

  7. Click Save.

  8. Complete other steps in Create and start a VM instance to finish creating the instance.

gcloud

To attach a tag to a resource during resource creation, add the --resource-manager-tags flag with the respective create command. For example, to attach a tag to a VM, use the following command:

gcloud compute instances create INSTANCE_NAME --resource-manager-tags=tagKeys/TAGKEY_ID=tagValues/TAGVALUE_ID

Replace the following:

  • INSTANCE_NAME: the name of your instance
  • TAGKEY_ID: the tag key number numeric ID
  • TAGVALUE_ID: the permanent numeric ID of the tag value that is attached; for example: 4567890123

Specify multiple tags by separating the tags with a comma, for example, TAGKEY1=TAGVALUE1,TAGKEY2=TAGVALUE2.

API

Make a POST request to the following URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/zones/ZONE/instances

Include the following request JSON body:

{
  "name": INSTANCE_NAME,
  "params": {
    "resourceManagerTags": {
      "tagKeys/TAGKEY_ID: "tagValues/TAGVALUE_ID",
    },
  }
  // other fields omitted
}

Replace the following:

  • INSTANCE_NAME: the name of your instance
  • TAGKEY_ID: the tag key number numeric ID
  • TAGVALUE_ID: the permanent numeric ID of the tag value that is attached; for example: 4567890123

Detaching a tag from a resource

You can detach a tag from a resource by deleting the tag binding resource.

To review instructions on how to detach tags, see Detaching a tag from a resource in the Resource Manager documentation.

Console

Depending on the resource type, the exact steps might be a bit different. For example, the following steps detaches a tag from a VM:

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select your project and click Continue.

  3. In the Name column, click the name of the VM for which you want to add tags.

  4. From the VM instance details page, complete the following steps:

    1. Click Edit.
    2. In the Basic section, click Manage Tags and remove the tags that you want for the instance.
    3. Click Save.

gcloud

The following example detaches a tag from a VM using the gcloud CLI:

gcloud resource-manager tags bindings delete \
--location LOCATION_NAME \
--tag-value=tagValues/TAGVALUE_ID \
--parent //compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID

Replace the following:

  • LOCATION_NAME: the region of the target resource, such as us-central1
  • TAGVALUE_ID: the numeric ID of the Tag key
  • PROJECT_NUMBER: the numeric ID your project
  • ZONE: the zone name such as us-central1-a
  • VM_ID: the numeric ID of the VM instance

To update or replace an existing tag binding to another one, detach the old tag binding and attach the new one.

API

To delete a tag binding attached to a resource, such as a VM, use the tagBindings.delete method with the regional endpoint where your resource is located.

DELETE https://LOCATION-cloudresourcemanager.googleapis.com/v3/{name=TAGBINDINGS_NAME}

Where:

  • TAGBINDINGS_NAME is the permanent ID of the TagBinding; for example: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F1234567890/tagValues/567890123456.

  • LOCATION is the regional endpoint for your resource; for example: us-central1.

Viewing tags attached to a resource

To review detailed instructions on how to list tags, see Listing tags attached to a resource in the Resource Manager documentation.

Console

Depending on the resource type, the exact steps might be a bit different. For example, the following steps show how to view tags for a VM:

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select your project and click Continue.

  3. In the Name column, click the name of the VM for which you want to view tags.

  4. From the VM instance details page, look for tags under the Tags section.

gcloud

To get a list of tag bindings directly attached to a resource, use the gcloud resource-manager tags bindings list command. If you add the --effective flag, you will also return a list of tags inherited by this resource. For example:

gcloud resource-manager tags bindings list \
    --location=LOCATION_NAME \
    --parent //compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID

Replace the following:

  • LOCATION_NAME: the region of the target resource, such as us-central1
  • PROJECT_NUMBER: the numeric ID your project
  • ZONE: the zone name such as us-central1-a
  • VM_ID: the numeric ID of the VM instance

If you add the --effective flag to the tags bindings list command, you will also return a list of all tags inherited by this resource. You should get a response similar to the following:

namespacedTagKey: 961309089256/environment
namespacedTagValue: 961309089256/environment/production
tagKey: tagKeys/417628178507
tagValue: tagValues/247197504380
inherited: true

If all tags evaluated on a resource are directly attached, the inherited field is false and is omitted.

API

To list the tag bindings attached to a regional resource, such as Compute Engine instances, use the tagBindings.list method with the regional endpoint where your resource is located. For example:

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

{
    "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID"
}

Replace the following:

  • LOCATION_NAME: the region to of the target resource, such as us-central1
  • PROJECT_NUMBER: the numeric ID your project
  • ZONE: the zone name such as us-central1-a
  • VM_ID: the numeric ID of the VM instance

What's next