This document provides a brief overview of labels and its features.

What are labels?

A label is a key-value pair that you can assign to Google Cloud resources.They help you organize these resources and manage your costs at scale, with thegranularity you need. You can attach a label to each resource, then filter theresources based on their labels. Information about labels is forwarded to the billing system thatlets you break down your billed charges by label. With built-inbilling reports,you can filter and group costs by resource labels. You can also use labels toquerybilling data exports.

Requirements for labels

The labels applied to a resource must meet the followingrequirements:

• Each resource can have up to 64 labels.
• Each label must be a key-value pair.
• Keys have a minimum length of 1 character and a maximum length of 63characters, and cannot be empty. Values can be empty, and have a maximum lengthof 63 characters.
• Keys and values can contain only lowercase letters, numeric characters,underscores, and dashes. All characters must use UTF-8 encoding, andinternational characters are allowed. Keys must start with a lowercase letter orinternational character.
• The key portion of a label must be unique within a single resource.However, you can use the same key with multiple resources.

These limits apply to the key and value for each label, and to theindividual Google Cloud resources that have labels. Thereis no limit on how many labels you can apply across all resourceswithin a project.

Common uses of labels

Here are some common use cases for labels:

• Team or cost center labels: Add labels based on team orcost center to distinguish resources owned by differentteams (for example,team:research andteam:analytics). You can use thistype of label for cost accounting or budgeting.

• Component labels: For example,component:redis,component:frontend,component:ingest, andcomponent:dashboard.

• Environment or stage labels: For example,environment:production andenvironment:test.

• State labels: For example,state:active,state:readytodelete, andstate:archive.

• Ownership labels: Used to identify the teams that areresponsible for operations, for example:team:shopping-cart.

• Network labels: A label can be attached toa virtual machine.Network tags that you defined in the past willappear as a label without a value.

Labels can be used as queryable annotations for resources, but can't be usedto set conditions on policies. Tags provide a way to conditionally allow ordeny policies based on whether a resource has a specific tag, by providing fine-grainedcontrol over policies. For more information, see theTags overview.

Permissions

The following permissions are required when you need to add, modify, and view labels for projects:

• You can add or modify a label by calling theprojects.patch() method. This requires theresourcemanager.projects.update permission.
• You can view a project's label by calling theprojects.get() method. This requires theresourcemanager.projects.get permission.

Understand costs using labels

You can attach a label to a resource and then filter resources based ontheir labels. Information about labels is forwarded to the billing system thatallows you tobreak down your billed chargesby label.

Here are some ways in which you can use labels to understand costs:

• You can add labels such ascostcenter=cost_center_name,service=service_name, andenvironment=environment_nameto your VMs or Cloud Storage buckets. This allows you to understand where your resourcesare deployed, for what purpose, and the cost center to which they should be charged.
• You can enable theexport of billing datato BigQuery. Labels are exported to BigQuery with thecorresponding Google Cloud resources and their usage. This allows you to monitoraspects such as the cost to run the shopping cart service in the applicationor the cost of developer test machines.
• You can use BigQuery in combination with labels to understand the cost of alltest system resources versus production resources or how much a particularservice costs.

Example

In this example, the cost ofplaylist services for a project is determined byexporting usage and labels to BigQuery.To do this, start by enabling the billing export to BigQuery.labels-demo-prjis the source of your resource usage andlabels_demo_bqexportis the destination dataset where usage data is stored. After you export yourusage and labels to BigQuery, you can determine how much yourplaylistservice costs are.

Here are the details of the Compute Engine usage and its associated cost in BigQuery.