Manage CMEK for CockroachDB Advanced

1. Make a note of your Cloud organization ID in the Organization settings page.
2. Find your Advanced cluster's ID. From the CockroachDB Cloud console Clusters list, click the name of a cluster to open its Cluster Overview page. From the page's URL make a note of the last 12 digits of the portion of the URL before /overview/. This is the cluster ID.

3. Use the cluster ID to find the cluster's associated cross-account IAM role, which is managed by CockroachDB Cloud.

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{YOUR_CLUSTER_ID} \
     --header 'Authorization: Bearer {YOUR_API_KEY}' | jq .account_id
   

   In the response, verify that the id field matches the cluster ID you specified, then make a note of the account_id, which is the ID for the cross-account IAM role.

1. Make a note of your Cloud organization ID in the Organization settings page.
2. Find your Advanced cluster's ID. From the CockroachDB Cloud console Clusters list, click the name of a cluster to open its Cluster Overview page. From the page's URL make a note of the last 12 digits of the portion of the URL before /overview/. This is the cluster ID.

3. Use the cluster ID to find the cluster's associated GCP Project ID, which is managed by CockroachDB Cloud. 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}"
   

   In the response, verify that the id field matches the cluster ID you specified, then make a note of the following:

   • account_id: the GCP project ID.
   • regions/name: one entry for each of the cluster's regions. CMEK must be configured in each of a cluster's regions.

     {
       "id": "blahblahblah-9ebd-43d9-8f42-589c9e6fc081",
       "name": "crl-prod-xyz",
       "cockroach_version": "v22.1.1",
       "plan": "DEDICATED",
       "cloud_provider": "GCP",
       "account_id": "crl-prod-xyz",
       "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": "crl-prod-xyz.gcp-us-east4.cockroachlabs.cloud",
           "ui_dns": "crl-prod-xyz.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
     }
   

4. Formulate the service account's email address, which is in the following format. Replace {cluster_id} with the cluster ID, and replace {account_id} with the GCP project ID.

   crl-kms-user-{cluster_id}@{account_id}.iam.gserviceaccount.com
   

Step 1. Provision the cross-account IAM role

Follow these steps to create a cross-account IAM role and give it permission to access the CMEK in AWS KMS. CockroachDB Cloud will assume this role to encrypt and decrypt using the CMEK.

1. Use the CockroachDB Cloud API to find the ID of the AWS account managed by CockroachDB Cloud that is associated with your cluster (not your own AWS account):

   curl --request GET \
        --url https://cockroachlabs.cloud/api/v1/clusters/{YOUR_CLUSTER_ID} \
        --header 'Authorization: Bearer {YOUR_API_KEY}'
   

   In the response, the ID is stored in the account_id field.

2. In the AWS console, visit the IAM page and select Roles and click Create role.

   • For Trusted entity type, select AWS account.
   • Select Another AWS account and set Account ID, provide the AWS account ID that you found in Before you begin.
   • Select Require external ID and set External ID to your CockroachDB Cloud organization ID, which you found in Before you begin.
   • Provide a name for the role. Do not enable any permissions.

3. Make a note of the Amazon Resource Name (ARN) for the new IAM role.

Step 1. Provision the cross-tenant service account

1. In the GCP Console, visit the IAM service accounts page for your project and click + Create service account. Select Cross-tenant.
2. Click the new service account to open its details.
3. In PERMISSIONS, click GRANT ACCESS.
   • For New principals, enter the service account ID for your cluster, which you found in Before you begin
   • For Role, enter Service Account Token Creator.

Click SAVE. 1. Make a note of the email address for the new service account.

1. Create a new file named cmek_config.json with the following contents. This file will contain a JSON array of region_spec objects, each of which includes the name of a CockroachDB Cloud region and a key_spec that specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key.

   Replace the placeholder values, being careful to include one region_spec object per cluster region. When enabling CMEK, you must include a region_spec for each region in the cluster.

   {
     "region_specs": [
       {
         "region": "{COCKROACHDB_CLOUD_REGION}",
         "key_spec": {
           "type": "AWS_KMS",
           "uri": "{YOUR_AWS_KMS_KEY_ARN}",
           "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
         }
       },
       {
         "region": "{COCKROACHDB_CLOUD_REGION}",
         "key_spec": {
           "type": "AWS_KMS",
           "uri": "{YOUR_AWS_KMS_KEY_ARN}",
           "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
         }
       }
     ]
   }
   

1. Set the required information as environment variables:

   export CLUSTER_REGION= # the region of the Advanced-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 tool 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
   

Appendix: IAM policy for the CMEK key

This IAM policy is to be attached to the CMEK key. It grants the required KMS permissions to the cross-account IAM role to be used by CockroachDB Advanced.

Note that this IAM policy refers to the ARN for the cross-account IAM role you created at the end of Step 1. Provision the cross-account IAM role.

{
  "Version": "2012-10-17",
  "Id": "crdb-cmek-kms",
  "Statement": [
      {
          "Sid": "Allow use of the key for CMEK",
          "Effect": "Allow",
          "Principal": {
              "AWS": "{ARN_OF_CROSS_ACCOUNT_IAM_ROLE}"
          },
          "Action": [
              "kms:Encrypt",
              "kms:Decrypt",
              "kms:GenerateDataKey*",
              "kms:DescribeKey",
              "kms:ReEncrypt*"
          ],
          "Resource": "*"
      },
      {
      {OTHER_POLICY_STATEMENT_FOR_ADMINISTRATING_KEY}
      }
  ]
}