Labeling keys

Cloud Key Management Service provides the option to add labels to your Cloud KMS keys. Labels are key-value pairs that you can use to group related Cloud KMS keys and store metadata about a Cloud KMS key.

Labels are included in your bill, so you can see the distribution of costs across your labels.

You can add, update, and remove key labels using the gcloud command-line tool and the Cloud KMS REST API.

You can use labels with other Google Cloud resources, such as virtual machine resources and storage buckets. For more information about using labels in Google Cloud, see Creating and Managing Labels.

What are labels?

A label is a key-value pair that helps you organize your Google Cloud Cloud KMS keys. You can attach a label to each resource, then filter the resources based on their labels. Information about labels is forwarded to the billing system, so you can break down your billing charges by label.

Common uses of labels

We do not recommend creating large numbers of unique labels, such as for timestamps or individual values for every API call. Here are some common use cases for labels:

  • Team or cost center labels: Add labels based on team or cost center to distinguish Cloud KMS keys owned by different teams (for example, team:research and team:analytics). You can use this type of label for cost accounting or budgeting.

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

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

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

Requirements for labels

The labels applied to a resource must meet the following requirements:

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

Creating a key with labels

When creating a key, you can add labels by providing one or more key value pairs as labels when you create your key.

gcloud

Add labels when you create a new key by providing the --labels flag, followed by a comma-separated list of key value pairs. For example, the following command adds two labels to the key, team=alpha and cost_center=cc1234:

 gcloud kms keys create key-name \
    --location location \
    --keyring keyring-name \
    --purpose purpose \
    --labels 'team=alpha,cost_center=cc1234'

If you provide the same label key twice, as in team=alpha,team=beta, the last specified value overrides earlier values. In this example team is set to beta.

API

Add labels when you create a new key by using the CryptoKeys.create method, and include the labels property in your request body. For example:

 {
  "purpose": "ENCRYPT_DECRYPT",
   "labels": [
   {
     "key": "team",
    "value": "alpha"
   },
   {
     "key": "cost_center",
     "value": "cc1234"
   }
  ]
 }
 

If you provide the same label key twice, the last specified value overrides earlier values. In this example team is set to beta.

"labels": [
{
  "key": "team",
  "value": "alpha"
},
{
  "key": "team",
  "value": "beta"
}
]

Viewing labels on a key

gcloud

To see the labels applied to a key, get a description of the key:

gcloud kms keys describe key-name \
  --location location \
  --keyring keyring-name

API

To see the labels applied to the key, use the cryptoKeys.get method:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location/keyRings/keyring-name/cryptoKeys/key-name"

Adding or updating labels

gcloud

Add or update labels to an existing key by using the update command, and provide the --update-labels flag followed by a comma-separated list of key value pairs. For example, this command adds the cost_center label if it doesn't exist, or updates the cost_center label if it already exists.

gcloud kms keys update key-name \
  --location location \
  --keyring keyring-name \
  --update-labels 'cost_center=cc5678'

API

Add or update labels to an existing key by using the CryptoKeys.patch method, and include the labels property in your request body. For example:

{
 ...,
  "labels": [
  {
    "key": "team",
    "value": "alpha"
  },
  {
    "key": "cost_center",
    "value": "cc5678"
  }
 ]
}

Removing labels

gcloud

Remove labels from an existing key by using the update command, and provide the --remove-labels flag, followed by a comma-separated list of label keys. For example, this command removes the team and cost_center labels. You do not need to specify the label values.

 gcloud kms keys update key-name \
  --location location \
  --keyring keyring-name \
  --remove-labels 'team,cost_center'

API

Remove labels from an existing key by using the CryptoKeys.patch method, and include the labels property as an empty array in your request body. For example:

{
 ...,
  "labels": [
 ]
}

Audit logging

Cloud Audit Logs for Cloud KMS can be used to log label information when keys are created or updated. Key creation and updates are both admin activities, and changes to labels are noted in the admin activity log.