Provision GCP for CMEK

This page covers the procedures required to provision Customer-Managed Encryption Keys (CMEK) for your CockroachDB Dedicated cluster with Google Cloud Platform (GCP).

This is part of the larger process of Enabling CMEK for a CockroachDB Dedicated cluster.

Overview

• In Step 1. Collect the required information, we'll gather the IDs and URLs necessary to bind together your CockroachDB organization and cluster, your own GCP project in which the CMEK will be managed, and the GCP project CockroachDB Dedicated uses to host your cluster.
• In Step 2. Provision the cross-tenant service account, we will create a service account for CockroachDB Dedicated to use to access the CMEK key for encrypt/decrypt actions.
• In Step 3. Create the CMEK key, we will explore two ways of creating the required key:
  • Directly in the GCP key management service (KMS) console
  • By setting up a Vault GCP-KMS secrets engine with access to GCP KMS, in order to leverage the security advantages of Vault's additional layer of abstraction.
    Note:

    Learn more about the integrations between CockroachDB and HashiCorp Vault.
• In Step 4. Authorize the service account to use the CMEK key, we will authorize the cross-tenant service account created in Step 1 to use the key created in Step 2.

Step 1. Collect the required information

Here we will create a cross-tenant service account that can be temporarily assumed by users in another GCP project, in this case, a project managed by CockroachDB Dedicated. This service account will have permissions to use the key for encryption and decryption.

1. Find your CockroachDB Dedicated organization ID in the CockroachDB Cloud organization settings page.

2. Find your CockroachDB Dedicated cluster ID:

   1. Visit the CockroachDB Cloud console cluster page.
   2. Click on the name of your cluster.
   3. Find your cluster ID in the URL of the single cluster overview page: https://cockroachlabs.cloud/cluster/<YOUR_CLUSTER_ID>/overview.

3. Find your CockroachDB Dedicated cluster's associated GCP Project ID.

   You must find the Project ID of the CockroachDB Dedicated-managed GCP Project associated with your cluster. To find this information, query the clusters endpoint of the CockroachDB Cloud API.

   CLUSTER_ID= #{ your cluster ID }
   API_KEY= #{ your API key }
   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID} \
     --header "Authorization: Bearer ${API_KEY}"
   

   {
     "id": "blahblahblah-9ebd-43d9-8f42-589c9e6fc081",
     "name": "docs-rule",
     "cockroach_version": "v22.1.1",
     "plan": "DEDICATED",
     "cloud_provider": "GCP",
     "account_id": "docs-rule-123",
     "state": "CREATED",
     "creator_id": "blahblahblah-3457-471c-b0cb-c2ab15834329",
     "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
     "config": {
       "dedicated": {
         "machine_type": "n1-standard-2",
         "num_virtual_cpus": 2,
         "storage_gib": 15,
         "memory_gib": 7.5,
         "disk_iops": 450
       }
     },
     "regions": [
       {
         "name": "us-east4",
         "sql_dns": "docs-rule.gcp-us-east4.cockroachlabs.cloud",
         "ui_dns": "docs-rule.gcp-us-east4.cockroachlabs.cloud",
         "node_count": 1
       }
     ],
     "created_at": "2022-06-16T17:24:06.262259Z",
     "updated_at": "2022-06-16T17:43:59.189571Z",
     "deleted_at": null
   }
   

   Record the following:

   • account_id: (the associated GCP Project ID)
   • id: your cluster ID
   • regions/name: the name of the region where the association GCP Project is located

Step 2. Provision the cross-tenant service account

1. Create a service account in your GCP project:

   1. In the GCP console, visit the IAM service accounts page for your project.
   2. Click + Create service account.

2. Authorize CockroachDB Dedicated's GCP project to use the service account (making it cross-tenant).

   1. Click your newly-created service account's email address to visit its details page.
   2. Select the PERMISSIONS tab and click GRANT ACCESS.

   3. For New principals, enter the service account ID for the CockroachDB Dedicated-managed service account to which you will grant access to this service account. The service account ID takes the following format: crl-kms-user-{CLUSTER_ID}@{PROJECT_ID}.iam.gserviceaccount.com

      Where CLUSTER_ID is the last 12 digits of your cluster ID, and PROJECT_ID is the GCP project ID, which you obtained previously.

   4. For Role, enter Service Account Token Creator.

   5. Click SAVE.

   Note:

   Note the email address for the service account (or keep the service account tab open), as you'll need it in Step 3.

Step 3. Create the CMEK key

Option A: Use the GCP console

1. In the GCP console, visit the KMS page.
2. Click + CREATE KEY RING and fill in the details to complete the key ring.

3. Fill in the details and CREATE your encryption key:

   1. Type: Generated key.
   2. Protection level: Software
   3. Purpose: Symmetric encrypt/decrypt
   Note:

   Keep your key ring name available, as you will need it.

Option B: Use the Vault GCP-KMS secrets engine to create the CMEK key

Before you begin

• You must have a Vault enterprise license.
• You must have Vault enterprise edition installed locally.

1. Provision a GCP service account for Vault to use to create your CMEK key.

   1. Visit the GCP IAM roles page and create a new role called cmek-vault-role.
   2. Add the required permissions specified in the Vault GCP-KMS documentation.
      Tip:

      You may need to add an additional permission cloudkms.importJobs.useToImport not mentioned in the Vault documentation.
   3. Visit the GCP IAM service accounts page and create a service account, called cmek-vault-agent.
   4. From the service account's details page, select the PERMISSIONS tab, and attach the cmek-vault-role.
   5. Generate credentials for the service account.
      1. Select the keys tab, and click ADD KEY.
      2. Choose Create new key and then JSON, which will generate a credential JSON and download it to your computer.
   Note:

   You will need the credential JSON file generated by GCP for the service account.

2. Create a KMS Key Ring in your GCP project.

   1. In the GCP console, visit the KMS page.
   2. Click + CREATE KEY RING and fill in the details to complete the key ring.
   Note:

   You will need the name of your key ring to configure your KMS provider record in Vault.

3. Initialize your shell for Vault:

    export VAULT_ADDR={YOUR_VAULT_TARGET}
    export VAULT_TOKEN={YOUR_VAULT_TOKEN}
    export VAULT_NAMESPACE="admin"
   

4. Enable the KMS secrets engine:

   vault secrets enable keymgmt
   

   Success! Enabled the keymgmt secrets engine at: keymgmt/
   

5. Connect Vault to your GCP account by creating a KMS provider entry:

   Note:

   credentials=service_account_file= must point to your credentials file generated for the service account.

   vault write keymgmt/kms/gcpckms \
   provider="gcpckms" \
   key_collection="projects/{YOUR_PROJECT_NAME}/locations/global/keyRings/{YOUR_KEY_RING_NAME}" \
   credentials=service_account_file="credentials.json"
   

   Success! Data written to: keymgmt/kms/gcpckms
   

6. Create an encryption key in Vault.

   This will generate the encryption key and store it in Vault. Note that at this point the key has not been imported into your GCP project's KMS service.

   vault write keymgmt/key/crdb-cmek-vault type="aes256-gcm96"
   

   Success! Data written to: keymgmt/key/aes256-gcm96
   

7. Propagate the key to your KMS service.

   vault write keymgmt/kms/gcpkms/key/crdb-cmek-vault \
       purpose="encrypt,decrypt" \
       protection="hsm"
   

   Success! Data written to: keymgmt/kms/gcpkms/key/crdb-cmek-vault
   

Step 4. Authorize the service account to use the CMEK key

1. From the GCP console KMS page, select your KMS key, which will be named crdb-cmek-vault-{RANDOM_SUFFIX} where RANDOM_SUFFIX is a string of random numbers.
2. Select the PERMISSIONS tab.
3. Click ADD.
4. For New principals, enter the email address for your cross-tenant service account created earlier.
5. Click Select a role and enter Cloud KMS CryptoKey Encrypter/Decrypter.
6. Click SAVE.
   Note:

   Keep your key name available, as you will need it.

Step 5. Build your CMEK configuration manifest

Compile the information about the service account and key we've just created into a manifest, which you will use to activate CMEK on your cluster with the CockroachDB Cloud API.

1. Set the required information as environment variables:

   export CLUSTER_REGION= # the region of the Dedicated-controlled GCP project where your cluster is located
   export GCP_PROJECT_ID= # your GCP project ID
   export KEY_LOCATION= # location of your KMS key (region or 'global')
   export KEY_RING= # your KMS key ring name
   export KEY_NAME= # your CMEK key name, i.e., crdb-cmek-vault-{RANDOM_SUFFIX}
   export SERVICE_ACCOUNT_EMAIL= # email for your cross-tenant service account
   

2. Then copy paste the following heredoc command to generate the YAML file, populating the values from your shell environment. (Alternatively, you can manually create the YAML file).

   <<YML > cmek_config.yml
   ---
   region_specs:
   - region: "${CLUSTER_REGION}"
     key_spec:
       type: GCP_CLOUD_KMS
       uri: "projects/${GCP_PROJECT_ID}/locations/${KEY_LOCATION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME}"
       auth_principal: "${SERVICE_ACCOUNT_EMAIL}"
   YML
   

3. Use ruby (or another technique), to compile human-editable YAML into API-parsable JSON:

   ruby -ryaml -rjson -e 'puts(YAML.load(ARGF.read).to_json)' < cmek_config.yml > cmek_config.json
   

4. Use the shell utility JQ to inspect JSON payload:

   Note:

   On a Mac, install JQ with brew install jq

   cat cmek_config.json | jq
   

After you have built your CMEK configuration manifest with the details of your cluster and provisioned the service account and KMS key in GCP, return to Enabling CMEK for a CockroachDB Dedicated cluster.