Configuring Network Tags

Network tags are text attributes you can add to Compute Engine virtual machine (VM) instances. Tags allow you to make firewall rules and routes applicable to specific VM instances.

You can only add network tags to VM instances or instance templates. You cannot tag other GCP resources. You can assign network tags to new instances at creation time, or you can edit the set of assigned tags at any time later. Network tags can be edited without stopping an instance.

Specifications

The network tags that you assign to an instance only apply to the VPC network where the instance's primary network interface is located:

  • This is true even for VPC Network Peering, because peered networks remain distinct networks. Thus, the network tags are still only meaningful in the network that contains the instance's primary network interface.

  • Network tags do not apply to alias IPs or multiple network interfaces.

Permissions

The following IAM roles are required for tasks discussed on this page. For more details, see Compute Engine IAM roles.

Task Required Role
Assign a network tag to a new instance when it is created Project owner or editor or Instance Admin
Add or remove network tags for existing instances
Add, remove, or edit firewall rules Project owner or editor or Security Admin

Limits

The following limits apply to network tags:

Limit Value Description
Maximum number of tags per VM 64 All tags for a VM must be unique. You can assign up to 64 different tags per VM.
Maximum number of characters for each tag 63
Acceptable characters for a tag lowercase letters, numbers, dashes Additionally, tags must start and end with either a number or a lowercase letter.

Firewall rules and routes

Network tags allow you to apply firewall rules and routes to a specific instance or set of instances:

  • You make a firewall rule applicable to specific instances by using target tags and source tags.

  • You make a route applicable to specific instances by using a tag.

Targets for firewall rules

Every firewall rule in GCP must have a target which defines the instances to which it applies. The default target is all instances in the network, but you can specify instances as targets using either target tags or target service accounts.

The target tag defines the GCP VMs to which the rule applies. The rule will be made applicable to the primary internal IP address of any instance having a matching network tag.

Both ingress and egress firewall rules have targets:

  • Ingress rules apply to traffic entering your VPC network. For ingress rules, the targets are destination VMs in GCP.

  • Egress rules apply to traffic leaving your VPC network. For egress rules, the targets are source VMs in GCP.

Consider an ingress firewall rule that allows traffic on TCP port 80 from any source. The rule has a target tag of http-server. This rule would apply only to instances that have the http-server network tag, which means that incoming traffic on port 80 would be allowed to those instances.

Source filters for ingress firewall rules

When you create ingress firewall rules, you must specify a source. You can define it using ranges of either internal or external IP addresses or by referring to specific instances. You specify instances using either source tags or source service accounts.

The source tag for an ingress firewall rule defines a source of traffic as coming from the primary internal IP address of any instance having a matching network tag.

You can use a combination of IP ranges and source tags or a combination of IP ranges and source service accounts. You cannot use both network tags and service accounts in the same rule. For more information about source tags and service accounts, see filtering by service account vs. network tag.

Interaction with routes

When you create a route, you can specify tags so that it is only applicable to traffic sent from the primary internal IP address of instances with matching network tags.

Adding and removing tags

Adding tags

Console

  1. Go to the VM instances page.
    Go to the VM instances page
  2. Select an instance.
  3. On the VM instance details page, click Edit.
  4. In the Network tags section, specify one or more tags, separated by commas.
  5. Click Save.

gcloud

To assign new tags to an instance, use the following gcloud command. Replace [INSTANCE-NAME] with the name of the instance, [ZONE] with its zone, and [TAGS] with a comma-delimited list of strings:

gcloud compute instances add-tags [INSTANCE-NAME] \
    --zone [ZONE] \
    --tags [TAGS]

See the gcloud documentation for more information.

Removing tags

Console

  1. Go to the VM instances page.
    Go to the VM instances page
  2. Select an instance.
  3. On the VM instance details page, click Edit.
  4. In the Network tags section, remove tags by clicking remove (X).
  5. Click Save.

gcloud

To remove tags from an instance, use the following gcloud command. Replace [INSTANCE-NAME] with the name of the instance, [ZONE] with its zone, and [TAGS] with a comma-delimited list of the tags to remove:

gcloud compute instances remove-tags [INSTANCE-NAME] \
    --zone [ZONE] \
    --tags [TAGS]

See the gcloud documentation for more information.

Direct API requests

You can set the network tags associated with an instance by making a direct API request. Unlike using the GCP Console or gcloud commands, updating tags by direct API request does not preserve any existing tags. Ensure that you specify the complete set of tags that should be associated with an instance whenever you update tags in this way.

To update tags using a direct API request:

  1. Determine the latest fingerprint associated with the tags. The fingerprint is used to prevent any collisions from simultaneous API requests. The process of updating network tags for an instance is similar to updating instance metadata.

    Perform a GET request to the instance; for example:

    GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance
    

    Look for the tags.fingerprint property in the response:

    200 OK
    {
    ...
    "tags": {
     "items": [
     "http-server",
     "db-client"
     ],
     "fingerprint": "MW8EqhxILtc="
    },
    ...
    }
    

    You can also use a gcloud command to get the fingerprint, as shown in the following example:

    gcloud compute instances describe [INSTANCE-NAME] \
       --zone [ZONE] \
       --format="get(tags.fingerprint)"
  2. Make a POST request to the instance().setTags method. The request body must contain all of the tags that should be associated with the instance along with the fingerprint value.

    Example request:

    POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setTags
    {
     "items": [
      "http-server",
      "db-client",
      "allow-internet-access"
      ],
     "fingerprint": "MW8EqhxILtc="
    }
    

    Example response:

    200 OK
    {
          "kind": "compute#operation",
          "id": "9251830049681941507",
          "name": "operation-1442414898862-51fde63aa57b1-422323e0-c439fb04",
          "zone": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
          "operationType": "setTags",
          "targetLink": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance",
          "targetId": "4392196237934605253",
          "status": "PENDING",
          "user": "user@example.com",
          "progress": 0,
    ...
    }
    

What's next

Was this page helpful? Let us know how we did:

Send feedback about...