Use CMEK

This page describes how to create, configure, and apply customer-managed encryption keys (CMEK) for AlloyDB for PostgreSQL.

To learn more about CMEK, see About CMEK.

Create and authorize a CMEK key for AlloyDB

1. Create a key in Cloud Key Management Service (Cloud KMS). AlloyDB supports the following kinds of keys:

   • Symmetric keys
   • Cloud HSM keys
   • Cloud External Key Manager (Cloud EKM) keys

   The key must be in the same location as your AlloyDB cluster. For example, a AlloyDB cluster located in us-west1 can use only keys in us-west1.

   If you already have a Cloud KMS key in the correct location, you can skip this step.

2. Grant AlloyDB access to the key.

   1. Using the Google Cloud CLI, create and display the service agent, or display it if the account already exists:

      gcloud beta services identity create --service=alloydb.googleapis.com \
          --project=PROJECT

      The gcloud services identity command creates or gets the service agent that AlloyDB can use to access the Cloud KMS key on your behalf.

      The service account ID resembles an email address:

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

   2. Grant the cloudkms.cryptoKeyEncrypterDecrypter role to the service account:

      gcloud kms keys add-iam-policy-binding KEY \
          --location REGION \
          --keyring KEYRING \
          --project=PROJECT \
          --member serviceAccount:service-xxx@gcp-sa-alloydb.iam.gserviceaccount.com \
          --role roles/cloudkms.cryptoKeyEncrypterDecrypter

      Replace the following:

      • KEY: the Cloud KMS ID of the key
      • REGION: the key's region—for example, us-central1
      • PROJECT: the ID of the key's project
      • KEYRING: the ID of the key's Cloud KMS keyring

      This role ensures the service account has permission to both encrypt and decrypt with the Cloud KMS key. For more information, see Cloud KMS Permissions and Roles.

Create a CMEK-encrypted cluster

When creating a new cluster, you can choose whether to encrypt it with the default Google-managed encryption or to use a CMEK key instead. For more information, see Create a cluster and its primary instance.

View a cluster's encryption method and CMEK key

gcloud alloydb clusters describe CLUSTER \
--project=PROJECT \
--region=REGION

Apply CMEK to backups

When creating a new backup, you can choose whether to encrypt it with the default Google-managed encryption or to use a CMEK key instead. For more information, see Create an on-demand backup or Schedule automatic backups.

You also have the option to apply a CMEK key to the cluster created when restoring from a backup, regardless of that backup's encryption method. For more on this, see Restore a cluster.

View a backup's encryption method and CMEK key

gcloud alloydb backups describe CLUSTER \
--project=PROJECT \
--region=REGION

Disable a key

Disabling a cluster's CMEK key makes that cluster's data inaccessible until you enable the key again.

However, disabling a key can take up to three hours to propagate to your AlloyDB cluster. To disable a key while preventing access to your data immediately, follow these steps:

1. Delete your cluster's primary instance. This does not affect your cluster's data. You can create a new primary instance after re-enabling the key, as described in the following section.

2. Use Cloud KMS to disable the key.

Enable a key

To enable a key, follow these steps:

1. Use Cloud KMS to enable the key.

2. If you deleted your cluster's primary instance before disabling your key, create a new primary instance.

Enabling a key can take up to three hours to propagate to your cluster. The cluster's data becomes accessible as soon as this propagation happens.

View audit logs for a Cloud KMS key

To view audit logs associated with a particular CMEK key, follow these steps:

1. Make sure that logging is enabled for the Cloud KMS API in your project.

2. Go to the Logs Explorer in the Google Cloud console.

   Go to the Logs Explorer

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

   resource.type="cloudkms_cryptokey"
   resource.labels.location="REGION"
   resource.labels.key_ring_id="KEYRING"
   resource.labels.crypto_key_id="KEY"
   

   Replace the following:

   • REGION: the key's region—for example, us-central1
   • KEYRING: the ID of the key's Cloud KMS keyring
   • KEY: the Cloud KMS ID of the key

4. Under normal operations, encrypt and decrypt operations are logged with INFO severity. These entries are logged when the instances in your AlloyDB cluster validate the {kms_name_short}} key, which occurs about every five minutes.

5. If AlloyDB fails to access the key, the operations are logged as ERROR.

View access justifications for a Cloud EKM key

If you use a Cloud EKM key, then you can use Key Access Justifications to view the reason for each Cloud EKM request. Additionally, based on the justification provided, you can automatically approve or deny a request. For more information, see View and act on justifications.