Using customer-managed encryption keys (CMEK)

This page describes how to set up a service account and keys for customer-managed encryption keys, and how to create an instance that uses a customer-managed encryption key. To learn more about using customer-managed encryption keys with Cloud SQL, see Overview of customer-managed encryption keys.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Console, on the project selector page, select or create a Cloud project.

    Go to the project selector page

  3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.

  4. Install and initialize the Cloud SDK.
  5. Make sure you have the Cloud SQL Admin role on your user account.

    GO TO THE Cloud IAM PAGE

  6. Enable the Cloud Key Management Service API.

    Enable the API

Workflow for creating a Cloud SQL instance with CMEK

  1. Create a service account for each project that requires customer-managed encryption keys.
  2. Create a keyring and key, and set the location for each key.
  3. Grant the key access to the service account.
  4. Note the key ID (KMS_RESOURCE_ID) and location. You need this information to create instances enabled with CMEK.
  5. Go to a project and create a Cloud SQL instance with the following options:
    1. The same location as the customer-managed encryption key
    2. The customer-managed key configuration
    3. The customer-managed encryption key ID

Your Cloud SQL instance is now enabled with CMEK.

You need to create a service account for each project that requires customer-managed encryption keys. Currently, you can only use gcloud command-line tool commands to create the type of service account you need for customer-managed encryption keys.

To create a service account with gcloud command-line tool, run the following command:

gcloud beta services identity create --service=sqladmin.googleapis.com \
             --project=[USER_PROJECT]

The previous command returns a service account name, using the following format:

service-[PROJECT_NUMBER]@gcp-sa-cloud-sql.iam.gserviceaccount.com

For example:

service-534582264470@gcp-sa-cloud-sql.iam.gserviceaccount.com

You use this service account name during the procedure in Granting the key access to the service account.

Creating a key

You can create the key in the same GCP project as the Cloud SQL instance or in a separate user project. The Cloud KMS key ring location must match the region where you want to create Cloud SQL instance. A multi-region or global region key will not work. The Cloud SQL instance create request fails if the regions don't match.

To create a Cloud KMS key:

CONSOLE

  1. Go to the Cryptographic keys page.

    GO TO THE CRYPTOGRAPHIC KEYS PAGE

  2. Click CREATE KEY RING.

  3. Add a Key ring name.

  4. Add a Key ring location.

  5. Click CREATE. The Create key page opens.

  6. Add a Key name.

  7. Select a Purpose (symmetric or asymmetric).

  8. Select a Rotation period and Starting on date.

  9. Click CREATE.

  10. On the Keys table, click the three dots in the last column, and select Copy Resource ID. This is the KMS_RESOURCE_ID. You need the KMS_RESOURCE_ID when creating the Cloud SQL instance.

GCLOUD

  1. Create a new key ring.

    gcloud kms keyrings create [KEYRING_NAME] --location [LOCATION]
    
  2. Create a key on the key ring.

    gcloud kms keys create [KEY_NAME] --location [LOCATION] \
          --keyring [KEYRING_NAME] --purpose encryption
    

Granting the key access to the service account

To grant access to the service account:

CONSOLE

  1. Go to the Cryptographic keys page.

    GO TO THE Cloud KMS PAGE

  2. Select the keys you created for customer-managed encryption keys.

  3. Select SHOW INFO PANEL.

  4. Click ADD MEMBER. add member button

  5. Add the service account name you created in New members.

  6. In Select a role, select Cloud KMS > Cloud KMS CryptoKey Encrypter/Decrypter.

  7. Click SAVE.

  8. Return to the Cryptographic keys page and select the key again.

  9. Select the SHOW INFO PANEL. You should see roles on the **Role/Member **column.

GCLOUD

gcloud kms keys add-iam-policy-binding \
       [KEY_NAME] --location [LOCATION] --keyring [KEY_RING_NAME] \
       --member serviceAccount:service-[PROJECT_NUMBER]@gcp-sa-cloud-sql.iam.gserviceaccount.com \
       --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Creating a Cloud SQL instance with CMEK

To create an instance with customer-managed encryption keys:

GCLOUD

gcloud beta sql instances create [INSTANCE_NAME] \
--project [PROJECT_ID] \
--disk-encryption-key [KMS_RESOURCE_ID] \
--database-version=SQLSERVER_2017_STANDARD \
--cpu=[NUMBER_CPUS] \
--memory=[MEMORY_SIZE] \
--root-password=[INSERT-PASSWORD-HERE]

CURL

To create an instance with customer-managed encryption keys, pass diskEncryptionConfiguration to the command. The value of this parameter is the KMS_RESOURCE_ID you received from the Creating a key procedure.

This cURL command uses Instances:Insert.

Creating a backup for a CMEK-enabled instance

When you create a backup of a Cloud SQL instance, the backup is encrypted with the same customer-managed encryption key as the primary instance.

See Creating and managing on-demand and automatic backups. The only change is that you see a warning on the Create a backup page that says: "Your backup will be encrypted with this instance's customer-managed encryption key. If anyone destroys this key, all data encrypted with the key will be permanently lost."

Disabling and re-enabling key versions

See the following topics:

Troubleshooting

This section describes things to try when you get an error message while setting up or using CMEK-enabled instances.

Cloud SQL administrator operations, such as create, clone, or update, might fail due to Cloud KMS errors, and missing roles or permissions. Common reasons for failure include a missing Cloud KMS key version, a disabled or destroyed Cloud KMS key version, insufficient IAM permissions to access the Cloud KMS key version, or the Cloud KMS key version is in a different region than the Cloud SQL instance. Use the following troubleshooting table to diagnose and resolve common problems.

Customer-managed encryption keys troubleshooting table

For this error... The issue might be... Try this...
Per-product, per-project service account not found The service account name is incorrect. Make sure you created a service account for the correct user project.

GO TO THE SERVICE ACCOUNTS PAGE.

Cannot grant access to the service account The user account does not have permission to grant access to this key version. Add the Organization Administrator role on your user or service account.

GO TO THE IAM ACCOUNTS PAGE

Cloud KMS key version is destroyed The key version is destroyed. If the key version is destroyed, you cannot use it to encrypt or decrypt data.
Cloud KMS key version is disabled The key version is disabled. Re-enable the Cloud KMS key version.

GO TO THE CRYPTO KEYS PAGE

Insufficient permission to use the Cloud KMS key The cloudkms.cryptoKeyEncrypterDecrypter role is missing on the user or service account you are using to run operations on Cloud SQL instances, or the Cloud KMS key version doesn't exist. Add the cloudkms.cryptoKeyEncrypterDecrypter role on your user or service account.

GO TO THE IAM ACCOUNTS PAGE


If the role is already on your account, see Creating a key to learn how to create a new key version. See note.
Cloud KMS key is not found The key version does not exist. Create a new key version. See Creating a key. See note.
Cloud SQL instance and Cloud KMS key version are in different regions The Cloud KMS key version and Cloud SQL instance must be in the same region. It does not work if the Cloud KMS key version is in a global region or multi-region. Create a key version in the same region where you want to create instances. See Creating a key. See note.

What's next