Using labels to organize Google Cloud Platform resources

Introducing labels, a tool to help you organize your Google Cloud Platform resources by allowing you to attach metadata to them. For example, you can label resources by environment (e.g., test, prod) plus owner (e.g., rae, bob) and you’ll know what they’re used for and who the owners are to contact. Filtering with labels helps you to easily find the resources you’re looking for. You can also use labels to build scripts that analyze costs or run bulk operations.

How do you add a label?

In the Developers Console, you can add, view and modify labels by selecting the resources you want to label, either a project or virtual machine instance and then clicking “Edit labels.”

After you have created a label, you can also add it as a column in your VM list view.

How do you filter with labels?

After adding labels to your resources, you can filter these resources using your labels. Just type a key or value into the Search box in the Developers Console and the filter box will auto suggest the right queries and allow you to preview results.

Common Uses

Here are some typical ways for you to use labels:

• Label based on team or Cost Center – To distinguish projects owned by different teams. This can be used in cost accounting or budgeting. For example team:marketing, team:research
• Label based on component – For example, component:redis, component:frontend
• Label based on environment or stage – For example, environment:prod, environment:test
• Label based on owner or contact – If there’s an individual who’s responsible for a resource and is the primary contact for the resource
• Label based on state – For example, state:inuse, state:readyfordeletion

Elements of a label

• A label is a key:value pair that can be attached to a project or a VM
• Label keys and non-empty label values can contain lowercase letters, digits and hyphens, must start with a letter, and must end with a letter or digit. The regular expression is [a-z0-9][a-z0-9._\-]*
• The length of labels keys and values is up to 63 characters
• There can be a maximum of 64 labels per resource
• VM tags you defined in the past will also show up as value-less labels

What about APIs?

You can access labels in APIs as well as the Developers Console. Below is an example that creates and filters VMs by labels. You might also want to read the API documentation for project labels and VM labels.

Setting VM labels

You can update the labels on an instance with a POST request to the setLabels path. You’ll need the project ID, zone and instance name for the request, and you’ll need an OAUTH token for authentication. The JSON request body should contain the new set of labels plus the labels fingerprint. The fingerprint is a hash of the existing labels, which is returned when you do a GET on the resource. This performs optimistic locking and prevents multiple requests from being made on the same resource.

Note that setLabels replaces ALL the labels for an instance, following the read-modify-write pattern. If you want to update a subset of the labels, you’ll want to read out the labels, make the changes needed and then call setLabels with the full list of labels.

$ curl --request POST --header "Authorization: Bearer your-oauth-token" --header 'Content-Type: application/json' --data '{"labels": {"env": "canary"}, "labelFingerprint": "abcdefghij="}' https://www.googleapis.com/compute/alpha/projects/your-project-id/zones/your-zone/instances/your-instance/setLabels
{
"kind": "compute#operation",
"id": "1234567890",
…
"selfLink": "https://www.googleapis.com/compute/alpha/projects/your-project-id/zones/your-zone/operations/operation-12345678"
}

Filtering by label in list requests

After you've set the labels, you can write a filter such as: “labels.env eq prod” which will only return instances that have the “env” label set to “prod.”

$ curl --header "Authorization: Bearer your-oauth-token" https://www.googleapis.com/compute/alpha/projects/your-project-id/zones/your-zone/instances?filter=%28labels.env+eq+canary%29+%28labels.tier+eq+backend%29
{
"items": [
{
"name": "vm42"
"labels": {
"env": "prod",
"tier": "backend"
    }
   }
 ]
}

Now that you know how to create labels and filter by them, you can use labels to better manage your resources on Google Cloud Platform.

Happy Labeling!

-Posted by Rae Wang, Product Manager, Google Cloud Platform