Use customer-managed encryption keys (CMEK)

This page describes how to perform tasks related tocustomer-managed encryption keys (CMEK) for Bigtable. For more information about CMEK in general, including when andwhy to enable it, see theCloud KMS documentation.

We recommend that you use the Google Cloud console for all key managementtasks. If you plan to use the Google Cloud CLI,install the gcloud CLI for Bigtable.

Prepare your CMEK keys

Before you can create a CMEK-protected Bigtable resource, youneed to complete the following steps to create a CMEK key for each region thatthe instance's clusters will be in:

  1. Create (or retrieve) a Bigtable service agent.
  2. Create a CMEK key.
  3. Configure IAM settings for that key.
Note: Thegcloud commands on this page show placeholders for twoGoogle Cloud projects: the project that contains Bigtableresources,CBT_PROJECT, and the project that contains yourCMEK key(s),KMS_PROJECT. However, you can use the sameproject for your Bigtable resources and CMEK keys.

Create a Bigtable service agent

Before you create a CMEK key, you must have a Bigtableserviceagent, which Bigtable uses to access the key.

Console

You can't create a service agent in the Google Cloud console. Bigtable might automatically provision a service agent during the instance creation workflow when youcreate or select your key. Additionally, when you select a customer-managed key, the console checks for the service agent. One of the following results might happen:

  • If the service agent exists, you are prompted to grant it the Cloud KMS Encrypter/Decrypter role.
  • If the service agent is not automatically provisioned or you encounter errors during key selection, use thegcloud tab to manually create the agent and grant the necessary permissions.

gcloud

  1. Run thegcloud services identity create command toview the service agent that Bigtable uses to access the CMEKkey on your behalf. This command creates the service account if it does notalready exist, then displays it.

    gcloud beta services identity create \    --service=bigtableadmin.googleapis.com \    --projectCBT_PROJECT

    ReplaceCBT_PROJECT with the project that containsyour Bigtable resources.

    The command displays the service agent ID, which isformatted like an email address. Record the output email string, becauseyou'll use it in a later step.

    Service identity created:service-xxx@gcp-sa-bigtable.iam.gserviceaccount.com

Create a key

You can use a key created directly in Cloud KMS or an externallymanaged key that you make available withCloud External Key Manager.

  1. In the Google Cloud project where you want to manage your keys:

    1. Enable the Cloud KMS API.

    2. Create a key ring and a key using one of the following options:

      The Cloud KMSkey location must be thesame as the Bigtable cluster that it will be used with.For example, if you create a key ring and key inus-central1 (Iowa),then clusters inus-central1-a,us-central1-b, andus-central1-ccan be protected by keys from that key ring.

Configure IAM settings for the key

Console

To grant an Cloud KMS role to your service agent, do thefollowing. You are also able to grant permission at the key or key-ringlevel if you want lower granularity.

  1. In the Google Cloud console, go to theIAM page.

    Goto the IAM page

  2. ClickAdd.

  3. Enter the email-formatted ID for your Bigtableservice agent.

  4. Select theCloud KMS CryptoKey Encrypter/Decrypter role.

  5. ClickSave.

gcloud

  1. Grant thecloudkms.cryptoKeyEncrypterDecrypter role to yourservice agent:

    gcloud kms keys add-iam-policy-bindingKMS_KEY \    --keyringKMS_KEYRING\    --locationKMS_LOCATION \    --member serviceAccount:SERVICE_ACCOUNT_EMAIL \    --role roles/cloudkms.cryptoKeyEncrypterDecrypter \    --projectKMS_PROJECT

    Provide the following:

    • KMS_KEY: the name you assigned to the key
    • KMS_KEYRING: the KMS key ring that contains the key
    • KMS_LOCATION : the region that contains the key ring
    • SERVICE_ACCOUNT_EMAIL: the email-formatted identifierfor the service agent that you are granting access to
    • KMS_PROJECT: the project that contains the key

Create a CMEK-enabled instance

After your CMEK keys are created and configured, you can create a CMEK-protectedinstance. Existing Bigtable instances that are protected byGoogle default encryption cannot be converted to use CMEK; you can only choosean encryption type and key at the time of creation.

Follow the steps onCreate an instance to create yourCMEK-protected instance.

View the key in use

Information on key versions comes from theencryption_info field.

Note: When an instance's key version changes, the change is not immediatelypropagated to the table's encryption information. There might be a delay fromwhen the change occurs to when the change appears.

To view the CMEK key version information for a table, complete the followingsteps:

Console

  1. Go to the Bigtable instances page in theGoogle Cloud console.

    Open the instance list

  2. Click the name of the instance that contains the table to open theInstance Details page and view the list of clusters in the instance.

  3. Next to a cluster ID, click thekey name underEncryption key toview theVersions page for the cluster's key.

gcloud

For each cluster, you can confirm its CMEK configuration as follows:

    gcloud bigtable clusters describeCLUSTER_ID \        --instanceINSTANCE_ID --projectCBT_PROJECT

Provide the following:

  • CLUSTER_ID: the permanent identifier for the cluster
  • INSTANCE_ID: the permanent identifier for the instance
  • CBT_PROJECT: the project that contains yourBigtable resources

The command displays output similar to the following:

    defaultStorageType: SSD    encryptionConfig:      kmsKeyName: projects/cloud-kms-project/locations/us-central1/keyRings/cloud-bigtable-keys/cryptoKeys/my-cmek-key    location: projects/cloud-bigtable-project/locations/us-central1-a    name: projects/cloud-bigtable-project/instances/cmek-test-instance/clusters/my-cluster    serveNodes: 1    state: READY

Disable a key

Disabling a CMEK key version suspends access to all data protected by that keyversion.Destroying a key version is the permanent(after 24 hours) counterpart of this action. Always disableall of the keysfor an instance rather than disabling only the keys for one or some clusters.

Note: Bigtable resources that are protected by a key version thatyou or another administrator have made inaccessible are automatically deletedafter 30 consecutive days. Destroying a key or revoking the Encrypter/Decrypterrole also triggers this 30-day time to live (TTL).Important: Always disableall key versions, not just the current primaryversion, when disabling a key. Because Bigtable is a distributedsystem, multiple key versions may be in use at any time, including while a keyrotation process is underway. For this reason, disabling the current primary keyversion may not prevent access to all the data that you intend to restrict.

Console

This is the recommended method. Using the Google Cloud console letsyou disable all versions of a key at once.

Followthese instructions for each key version.

gcloud

We recommend that youuse the Google Cloud console to disable keys.If you wish to use the Google Cloud CLI instead, run the followingcommands.

  1. List all versions of the CMEK key:

    gcloud kms keys versions list --keyKMS_KEY \    --keyringKMS_KEYRING --locationKMS_LOCATION \    --projectKMS_PROJECT

    Provide the following:

    • KMS_KEY: the name of the CMEK key
    • KMS_KEYRING: the KMS key ring that contains the key
    • KMS_LOCATION: the region that contains the key ring
    • KMS_PROJECT: the project that contains the key

    The output is similar to the following:

    NAME                                  STATEKMS_KEY_NAME/cryptoKeyVersions/1      ENABLEDKMS_KEY_NAME/cryptoKeyVersions/2      ENABLEDKMS_KEY_NAME/cryptoKeyVersions/3      ENABLEDKMS_KEY_NAME/cryptoKeyVersions/4      ENABLED

  2. Disableall versions:

    for $KV in 1 2 3 4;dogcloud kms keys versions disable KV --keyKMS_KEY \    --keyringKMS_KEYRING --locationKMS_LOCATION \    --projectKMS_PROJECT;done

    Provide the following:

    • 1 2 3 4: the versions that you are disabling
    • KMS_KEY: the name of the CMEK key
    • KMS_KEYRING: the KMS key ring that contains the key
    • KMS_LOCATION: the region that contains the key ring
    • KMS_PROJECT: the project that contains the key

    Listing all key versions again will show their state flipped toDISABLED, though it may take up to 4 hours for Bigtableto act on this state change.

  3. [Optional] To confirm the status of a disabled CMEK after you've waited4 hours, run the following command:

     gcloud bigtable instances tables describeTABLE_ID \     --instanceINSTANCE_ID --view ENCRYPTION \     --projectCBT_PROJECT

    Provide the following:

    • TABLE_ID: the permanent identifier for the table
    • INSTANCE_ID: the permanent identifier for the instance
    • CBT_PROJECT: the project that contains yourBigtable resources

    The command displays output similar to the following:

    clusterStates:CLUSTER:encryptionInfo:-encryptionStatus:code:9details:-'@type':type.googleapis.com/google.rpc.PreconditionFailureviolations:-subject:KMS_KEY_NAME/cryptoKeyVersions/<int>type:KEY_DISABLEDmessage:KMS_KEY_NAMEisnotenabled,currentstateis:DISABLED.encryptionType:CUSTOMER_MANAGED_ENCRYPTIONkmsKeyVersion:KMS_KEY_NAME/cryptoKeyVersions/<int>name:projects/CBT_PROJECT/instances/INSTANCE/tables/TABLE

  4. [Optional] To verify that the clusters in the instance are disabled,run the following command:

    gcloud bigtable clusters list --instancesINSTANCE_ID    --projectCBT_PROJECT

    Provide the following:

    • INSTANCE_ID: the permanent identifier for the instance
    • CBT_PROJECT: the project that contains yourBigtable resources

    The command displays output similar to the following:

    NAME              ZONE           NODES  STORAGE    STATEmy-cluster        us-central1-a  1      SSD        DISABLEDmy-other-cluster  us-central1-b  1      SSD        DISABLED

Enable a key

If a key version has been disabled, you can re-enable it to regain access toyour Bigtable resources. This option is available for 30 days fromthe time the key version is disabled.

Important: Because Bigtable is a distributed system, multiple keyversions might be in use at any time, such as when a key is automaticallyrotated to a new version. To avoid unexpected or unintended behavior and ensurethat all resources are correctly enabled,always enable all key versions,not just the current primary version, when enabling a key.

Console

This is the recommended method. Using the Google Cloud console letsyou enable all versions of a key at once.

Followthese instructions for each key version.

gcloud

We recommend that youuse the Google Cloud console to enable keys. Ifyou wish to use the Google Cloud CLI instead, run the followingcommands.

  1. View the versions list to identify all the versions of the key:

    gcloud kms keys versions list --keyKMS_KEY \    --keyringKMS_KEYRING --locationKMS_LOCATION \    --projectKMS_PROJECT

    Provide the following:

    • KMS_KEY: the name of the CMEK key
    • KMS_KEYRING: the KMS key ring that contains the key
    • KMS_LOCATION: the region that contains the key ring
    • KMS_PROJECT: the project that contains the key

    The command displays output similar to the following:

    NAME                                  STATEKMS_KEY_NAME/cryptoKeyVersions/1      DISABLEDKMS_KEY_NAME/cryptoKeyVersions/2      DISABLEDKMS_KEY_NAME/cryptoKeyVersions/3      DISABLEDKMS_KEY_NAME/cryptoKeyVersions/4      DISABLED

    Run thekms keys versions enable command, providingall versionsthat are listed. Using the example output, the command looks similar tothe following:

    for $KV in 1 2 3 4;dogcloud kms keys versions enable KV --keyKMS_KEY \    --keyringKMS_KEYRING --locationKMS_LOCATION \    --projectKMS_PROJECT;done

    Provide the following:

    • 1 2 3 4: the versions that you are disabling
    • KMS_KEY: the name of the CMEK key
    • KMS_KEYRING: the KMS key ring that contains the key
    • KMS_LOCATION: the region that contains the key ring
    • KMS_PROJECT: the project that contains the key

    Listing the key versions again shows their state flipped toENABLED.

View audit logs for a Cloud KMS key

Before you enable Cloud KMS Data Access audit logs, you should befamiliar withCloud Audit Logs.

Cloud KMS Data Access audit logs show you whenBigtable or any other products that are configured to use yourCMEK key make encrypt/decrypt calls to Cloud KMS.Bigtable does not issue an encrypt/decrypt call on every datarequest, but instead maintains a poller that checks the key periodically. Thepolling results appear in the audit logs.

You can set up and interact with the audit logs in theGoogle Cloud console:

  1. Make sure thatlogging is enabled for theCloud KMS API in your project.

  2. Go toCloud Logging in the Google Cloud console.

    Go to Cloud Logging

  3. Limit the log entries to your Cloud KMS key by adding thefollowing lines to the Query builder:

    resource.type="cloudkms_cryptokey"resource.labels.key_ring_id=KMS_KEYRINGresource.labels.crypto_key_id=KMS_KEY

    Provide the following:

    • KMS_KEY: the name of the CMEK key
    • KMS_KEYRING: the KMS key ring that contains the key

    The log shows a couple log entries about every five minutes per table ineach cluster. The log entries look similar to these examples:

    Info2021-03-2008:02:24.869EDTCloudkms.googleapis.comDecryptprojects/cloud-kms-project/locations/us-central1/keyRings/cloud-bigtable-keys/cryptoKeys/my-cmek-keyservice-123456789123@gcp-sa-bigtable.iam.gserviceaccount.comaudit_log,method:"Decrypt",principal_email:"service-1234567891011@gcp-sa-bigtable.iam.gserviceaccount.com"Info2021-03-2008:02:24.913EDTCloudkms.googleapis.comEncryptprojects/cloud-kms-project/locations/us-central1/keyRings/cloud-bigtable-keys/cryptoKeys/my-cmek-keyservice-123456789123@gcp-sa-bigtable.iam.gserviceaccount.comaudit_log,method:"Encrypt",principal_email:"service-123456789123@gcp-sa-bigtable.iam.gserviceaccount.com"

SeeUnderstanding audit logs for details aboutinterpreting audit logs.

View key usage

Cloud KMS lets you view the following information about the Bigtable resources that your keys protect.

  • Key usage summary: Includes information about the number of protected resources and projects that use the key.
  • Key usage detail: Identifies the resources that a key protects and the resources that depend on the key.

The following Bigtable resources are supported:

  • bigtableadmin.googleapis.com/Backup
  • bigtableadmin.googleapis.com/Cluster
  • bigtableadmin.googleapis.com/Table
  • bigtableadmin.googleapis.com/AuthorizedView

The following Bigtable resources are supported asPreview:

  • bigtableadmin.googleapis.com/LogicalView
  • bigtableadmin.googleapis.com/MaterializedView

For more information about viewing key usage, seeView key usage information.

View the encryption status of a table

Console

You are not able to view the encryption status of a table in theGoogle Cloud console.

gcloud

To view the CMEK details on a table, setview toENCRYPTION orFULL.The response includes the in-use key version and its status as seen byBigtable.

    gcloud alpha bigtable instances tables describeTABLE_ID \        --instanceINSTANCE_ID --view ENCRYPTION \        --projectCBT_PROJECT

Provide the following:

  • TABLE_ID: the permanent identifier for the cluster
  • INSTANCE_ID: the permanent identifier for the instancethat contains the backup
  • CBT_PROJECT: the project that contains yourBigtable resources

The command displays output similar to the following:

    clusterStates:      my-cluster:        encryptionInfo:- encryptionStatus: {}          encryptionType: CUSTOMER_MANAGED_ENCRYPTION          kmsKeyVersion: KMS_KEY_NAME/cryptoKeyVersions/4      my-other-cluster:        encryptionInfo:- encryptionStatus: {}          encryptionType: CUSTOMER_MANAGED_ENCRYPTION          kmsKeyVersion: KMS_KEY_NAME/cryptoKeyVersions/4      name: projects/cloud-bigtable-project/instances/cmek-test-instance/tables/my-table

View the encryption details for a backup

A backup stays pinned to its original key version.Key version rotations in Cloud KMS don't rotate the versions used to decryptbackups.

Console

  1. Go to the Bigtable instances page in theGoogle Cloud console.

    Open the instance list

  2. Click the instance name to open theInstance Details page.

  3. In the left navigation pane, clickBackups.

The key name and key version for each backup are listed underCustomer managed key.

gcloud

Run the following command to view encryption info for a backup.

    gcloud alpha bigtable backups describeBACKUP_ID \        --instanceINSTANCE_ID --clusterCLUSTER_ID \        --projectCBT_PROJECT

Provide the following:

  • BACKUP_ID: the ID assigned to the backup
  • CLUSTER_ID: the permanent identifier for the cluster
  • INSTANCE_ID: the permanent identifier for the instancethat contains the backup
  • CBT_PROJECT: the project that contains yourBigtable resources

The command returns output similar to the following. ThekmsKeyVersionis the CMEK key version that the backup is pinned to. The status of thekey version is not reported.

    encryptionInfo:      encryptionStatus:        code: 2        message: Status of the associated key version is not tracked.      encryptionType: CUSTOMER_MANAGED_ENCRYPTION      kmsKeyVersion: KMS_KEY_NAME/cryptoKeyVersions/3    endTime: '2020-09-01T00:03:26.568600Z'    expireTime: '2020-09-02T00:03:25.436473Z'    name: projects/cloud-bigtable-project/instances/cmek-test-instance/clusters/my-cluster/backups/my-backup    sizeBytes: '3780'

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.