Labeling Keys

Labels are a lightweight way to group together keys that are related or associated with each other, and are great for tracking items in billing. In addition to key rings, which allow keys to be grouped hierarchically, labels can be used to organize or keep track of keys in a way that makes the most sense for you. As an example, you can label keys by cost center or environment. Labels are optional.

In Google Cloud Key Management Service, only keys can be labelled.

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

Labels are key:value metadata pairs that allow you to group your keys. (The key in key:value refers to an attribute key, not a key.) For example, you can use labels to create a team key that has values alpha, beta, and delta, and apply the team:alpha, team:beta, and team:delta labels to different keys in order to indicate which team is associated with those keys.

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 Platform resources, such as virtual machine resources and storage buckets.

Before you begin

Specifications

You can apply multiple labels to each key, with a maximum of 64 labels per key.

  • Keys and values cannot be longer than 63 characters each.

  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.

  • Label keys must start with a lowercase letter. An international character is allowed.

  • Label keys cannot be empty.

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 CRYPTOKEY_NAME \
--location LOCATION --keyring KEYRING_NAME \
--purpose encryption --labels team=alpha,cost_center=cc1234

Note that if you provide the same label key twice, as in team=alpha,team=beta, the last specified value will go into effect, in this case, team=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"
  }
 ]
}

Note that if you provide the same label key twice, as in:

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

the last specified value will go into effect, in this case:

  {
    "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 CRYPTOKEY_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/CRYPTOKEY_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 CRYPTOKEY_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 CRYPTOKEY_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 Logging 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.

Send feedback about...

Cloud KMS Documentation