Labels, Tags, and Network Tags

GCP has three unrelated systems that all sound like "tags," and engineers conflate them constantly — with real consequences when the wrong one is used for IAM or firewalls. Labels are key/value metadata for billing breakdowns and organization. Resource Manager tags (google_tags_tag_key, _value, _binding) are a separate, governed system whose values can be targeted by IAM conditions and org policies. Network tags are plain strings stamped on a VM that firewall rules and routes match against.

They are not interchangeable. Using a label where a tag is required — or a network tag where a Resource Manager tag is — silently fails to do what you wanted, with no error to tell you. An AWS engineer arrives expecting one unified tag system that does cost, IAM conditions, and grouping at once; on GCP that one job is split across three mechanisms with different APIs and different Terraform resources. Knowing which is which is the whole topic.

Labels — Billing and Organization

Labels are free-form key/value pairs on most resources — labels = { team = "data", env = "prod" } — surfaced in billing exports and resource filters. They organize resources and attribute cost, and that is all. Nothing keys IAM off a label, and no firewall rule matches one. A label carries no access-control or policy meaning whatsoever; it is metadata for humans and cost reports.

The provider's default_labels stamps a consistent set across everything it manages, which is the practical way to get team, env, and cost-center onto every resource without repeating them. Use labels for billing attribution and filtering — and stop there, because the moment you expect a label to gate access you have reached for the wrong system.

resource "google_storage_bucket" "raw" {
  name     = "hatch-events-raw"
  location = "US"
  labels = {
    team = "data"      # shows up in billing export and filters
    env  = "prod"      # invisible to IAM conditions and firewalls
  }
}

Resource Manager Tags — Governed and IAM-Aware

google_tags_tag_key, google_tags_tag_value, and google_tags_tag_binding define a controlled vocabulary — a key environment with values prod and staging — and bind a value to a resource. Their distinguishing power is that IAM conditions and org policies can target them: you can grant a role only on resources tagged environment=prod, or write an org policy that keys off the tag. The tag values themselves have IAM controlling who may apply them, so the classification is governed, not free-form.

This is the system to reach for when a resource's classification must drive access control. The configuration below defines the key and value, then binds the value to a project — after which an IAM condition can reference that tag. Where a label is invisible to IAM, a Resource Manager tag is exactly what an IAM condition or org policy is built to target.

resource "google_tags_tag_key" "environment" {
  parent     = "organizations/123456789012"
  short_name = "environment"
}

resource "google_tags_tag_value" "prod" {
  parent     = google_tags_tag_key.environment.id
  short_name = "prod"
}

resource "google_tags_tag_binding" "app_prod" {
  parent    = "//cloudresourcemanager.googleapis.com/projects/hatch-app-prod"
  tag_value = google_tags_tag_value.prod.id   # IAM conditions can key off this
}

Network Tags — Firewall and Route Targeting

Network tags are plain strings in a VM's tags list — ["web", "ssh-allowed"] — and they have nothing to do with the other two systems. A firewall rule's target_tags and source_tags, and a route's tags, match these strings to decide which traffic reaches which VMs. There is no key, no governance, no billing role — just a label a firewall rule looks for. A network tag never appears in a cost report and is invisible to IAM.

There is a security caveat: anyone who can edit an instance's tags can pull it into a permissive firewall rule by adding the right string. For sensitive VMs, service-account-based firewall targeting is the tighter alternative — a firewall rule that matches the VM's service account cannot be subverted by editing a free-form tag list. Use network tags for ordinary targeting, but do not make them the sole gate in front of sensitive workloads.

Why They Get Confused

All three are colloquially "tags," which is the root of the confusion, and the AWS mental model makes it worse. AWS tags are one system that spans cost allocation, IAM Condition keys, and grouping all at once. The AWS engineer reaches for "tags" expecting that unified behavior and gets one of three GCP systems that each do only a slice of it. A label that does not gate IAM, a network tag that does not show in billing, a Resource Manager tag that a firewall rule ignores — each is "working as designed," just not the design the AWS habit assumed.

Choosing the Right One

The rule is short. Use labels to attribute cost and group resources. Use Resource Manager tags when you need IAM conditions or org policies to target a resource's classification. Use network tags only to wire VMs to firewall rules and routes. And never expect a label to gate access or a network tag to show up in billing — those are the two crossings that silently do nothing, and they are the ones engineers reach for most.