> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage CMEK for CockroachDB Advanced

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<InternalLink path="cmek">Customer-Managed Encryption Keys (CMEK)</InternalLink> for CockroachDB Cloud advanced allows the customer to delegate responsibility for the work of encrypting their cluster data to CockroachDB Cloud, while maintaining the ability to completely revoke CockroachDB Cloud's access.

This page shows how to enable <InternalLink path="cmek">Customer-Managed Encryption Keys (CMEK)</InternalLink> for CockroachDB Advanced.

## Prerequisites

To enable CMEK for a cluster, you need a CockroachDB Advanced <InternalLink path="private-clusters">private cluster</InternalLink> with <InternalLink path="create-an-advanced-cluster#step-6-configure-advanced-security-features">advanced security features</InternalLink> enabled. Advanced security features can be enabled only during cluster creation. Complete the steps in this guide before inserting data into the cluster.

This guide will walk you through creating the necessary cloud identities and encryption keys:

* An IAM role in your AWS account, a cross-tenant service account in your GCP project, or admin consent for CockroachDB Cloud to access your Azure Key Vault. CockroachDB Cloud will use this identity to encrypt and decrypt using the CMEK.
* A CMEK key for your cluster stored in AWS KMS, GCP KMS, or Azure Key Vault. CockroachDB Cloud never has access to the CMEK itself. You can use an existing key or create a new one following the instructions in this guide.

The instructions on this page describe how to enable and manage CMEK using the <InternalLink path="cloud-api">Cloud API</InternalLink> which requires a service account and corresponding access token. As an alternative to the API, you can use the CMEK UI <InternalLink version="releases" path="cockroachdb-feature-availability">Preview</InternalLink> in the Cloud Console.

## Enable CMEK

This section shows how to enable CMEK on a CockroachDB Advanced cluster.

Select your cluster's cloud provider to continue.

<AccordionGroup>
  <Accordion title="AWS">
    ### Before you begin

    1. Make a note of your Cloud organization ID in the [Organization settings page](https://cockroachlabs.cloud/settings).
    2. Find your CockroachDB Advanced cluster's ID. From the CockroachDB Cloud console [Clusters list](https://cockroachlabs.cloud/clusters), 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.

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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.

    ### 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):

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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](https://console.aws.amazon.com/iam) 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](#before-you-begin).
       * Select **Require external ID** and set **External ID** to your CockroachDB Cloud organization ID, which you found in [Before you begin](#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 2. Create the CMEK key

    If you intend to use an existing key as the CMEK, skip this step.

    You can create the CMEK directly in the AWS Console or using <InternalLink version="stable" path="hashicorp-integration">HashiCorp Vault</InternalLink>.

    <Tabs>
      <Tab title="AWS Console">
        1. In the AWS console, visit [AWS KMS](https://console.aws.amazon.com/kms).
        2. To create the key, select **Customer managed keys** and click **Create Key**.
           * Set **Key type** to **Symmetric Key**.
           * Set **Key usage** to **Encrypt and decrypt**.
           * Under **Advanced options**, set **Key material** to **KMS**, then choose whether to create a single-region or multi-region key. For optimal performance, we recommend serving the key in each of your cluster's regions.
           * Set **Alias** to a name for the key.
        3. Configure the permissions for your key using the following IAM policy:

           ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           {
             "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}
                 }
             ]
           }
           ```
        4. Finish creating the key.
      </Tab>

      <Tab title="Hashicorp Vault">
        1. [Install Vault Enterprise Edition installed locally](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?in=vault/enterprise).
        2. Configure Vault's authentication details:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
             export VAULT_ADDR={YOUR_VAULT_TARGET}
             export VAULT_TOKEN={YOUR_VAULT_TOKEN}
             export VAULT_NAMESPACE="admin"
           ```
        3. Enable Vault KMS Secrets Engine:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault secrets enable keymgmt
           ```
        4. Connect Vault to your AWS account by creating a KMS provider entry:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault write keymgmt/kms/awskms \
             provider="awskms" \
             key_collection="us-east-1" \
             credentials=access_key="{your access key}" \
             credentials=secret_key="{your secret key}"
           ```
        5. Create an encryption key in Vault. The key has not yet been imported into AWS KMS.

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault write keymgmt/key/crdb-cmek-vault type="aes256-gcm96"
           ```
        6. Import the key into AWS KMS:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault write keymgmt/kms/awskms/key/crdb-cmek-vault \
               purpose="encrypt,decrypt" \
               protection="hsm"
           ```
        7. In the AWS console, visit the [KMS page](https://console.aws.amazon.com/kms).
        8. Choose **Customer managed keys**.
        9. Select the key you just created in Vault, which will be prefixed with `crdb-cmek-vault`.
        10. Set the permissions policy for your key using the following IAM policy:

            ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
            {
              "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}
                  }
              ]
            }
            ```
        11. Save to finish creating the key.
      </Tab>
    </Tabs>

    ### Step 3. 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. 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.

       ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       {
         "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}"
             }
           }
         ]
       }
       ```

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

    <Note>
      On a Mac, install JQ with `brew install jq`
    </Note>

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    cat cmek_config.json | jq
    ```

    After you have built your CMEK configuration manifest with the details of your cluster and provisioned the necessary cloud identity and encryption key, proceed to Step 4.

    ### Step 4. Activate CMEK

    Using the CockroachDB Cloud API, send a `POST` request with the contents of `cmek_config.json` to the cluster's `cmek` endpoint.

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    CLUSTER_ID= #{ your cluster ID }
    API_KEY= #{ your API key }
    curl --request POST \
      --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
      --header "Authorization: Bearer ${API_KEY}" \
      --header "content-type: application/json" \
      --data "@cmek_config.json"
    ```
  </Accordion>

  <Accordion title="GCP">
    ### Before you begin

    1. Make a note of your Cloud organization ID in the [Organization settings page](https://cockroachlabs.cloud/settings).
    2. Find your CockroachDB Advanced cluster's ID. From the CockroachDB Cloud console [Clusters list](https://cockroachlabs.cloud/clusters), 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:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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.

         ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           {
             "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 <code>{'{cluster_id}'}</code> with the cluster ID, and replace <code>{'{account_id}'}</code> with the GCP project ID.

       ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       crl-kms-user-{cluster_id}@{account_id}.iam.gserviceaccount.com
       ```

    ### Step 1. Provision the cross-tenant service account

    1. In the GCP Console, visit the [IAM service accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) 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](#before-you-begin),
       * For **Role**, enter **Service Account Token Creator**.

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

    ### Step 2. Create the CMEK key

    If you intend to use an existing key as the CMEK, skip this step.

    You can create the CMEK directly in the GCP Console or using <InternalLink version="stable" path="hashicorp-integration">HashiCorp Vault</InternalLink>.

    <Tabs>
      <Tab title="GCP Console">
        1. In the GCP console, visit the [KMS page](https://console.cloud.google.com/security/kms).
        2. Click **+ CREATE KEY RING** and fill in the details to complete the key ring.
        3. In the next screen, configure your encryption key as desired. Set the following:
           * **Type**: **Generated key**.
           * **Protection level**: **Software**
           * **Purpose**: **Symmetric encrypt/decrypt**

             Click **Create**.

        Make a note of the key ring name.
      </Tab>

      <Tab title="Hashicorp Vault">
        1. In the GCP Console, visit the [KMS page](https://console.cloud.google.com/security/kms) and click **+ CREATE KEY RING** to create a key ring for your encryption key. Make a note of the name of the key ring, which you will provide to Vault to create your encryption key.
        2. Visit the [GCP IAM roles page](https://console.cloud.google.com/iam-admin/roles) and create a new role called `cmek-vault-role`. Add the required permissions specified in the [Vault GCP-KMS documentation](https://learn.hashicorp.com/tutorials/vault/key-management-secrets-engine-gcp-cloud-kms?in=vault/key-management#configure-cloud-kms). Also add the permission `cloudkms.importJobs.useToImport`, which allows the role to import keys into GCP.
        3. Visit the [GCP IAM service accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) and create a service account, called `cmek-vault-agent`. Vault will use this service account to create your CMEK key.
        4. From the service account's details page, select the **PERMISSIONS** tab, and attach the `cmek-vault-role`.
        5. To generate credentials for the service account, select the **keys** tab, and click **ADD KEY**. Choose **Create new key**, then select **JSON** to generate a credential file in JSON format and download it. You will need the credential JSON file generated by GCP for the service account. Store it in a secure location such as a password manager.
        6. [Install Vault Enterprise Edition installed locally](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?in=vault/enterprise).
        7. Configure Vault's authentication details:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
             export VAULT_ADDR={YOUR_VAULT_TARGET}
             export VAULT_TOKEN={YOUR_VAULT_TOKEN}
             export VAULT_NAMESPACE="admin"
           ```
        8. Enable Vault KMS Secrets Engine:

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault secrets enable keymgmt
           ```
        9. Connect Vault to your GCP project by creating a KMS provider entry. Replace <code>{'{SERVICE_ACCOUNT_FILE}'}</code> with the path to the JSON file you downloaded earlier and replace <code>{'{YOUR_PROJECT_NAME}'}</code> with your GCP project ID.

           ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
           vault write keymgmt/kms/gcpckms \
           provider="gcpckms" \
           key_collection="projects/{YOUR_PROJECT_NAME}/locations/global/keyRings/{YOUR_KEY_RING_NAME}" \
           credentials=service_account_file="{SERVICE_ACCOUNT_FILE}"
           ```
        10. Create the encryption key in Vault:

            ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
            vault write keymgmt/key/crdb-cmek-vault type="aes256-gcm96"
            ```
        11. Import the key into GCP KMS:

            ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
            vault write keymgmt/kms/gcpkms/key/crdb-cmek-vault \
                purpose="encrypt,decrypt" \
                protection="hsm"
            ```
        12. To authorize the service account to use the CMEK key, visit the [GCP console KMS page](https://console.cloud.google.com/security/kms) and select your KMS key, which will be prefixed with `crdb-cmek-vault`. From the the **PERMISSIONS** tab, click **ADD**.
            * For **New principals**, enter the email address for your cross-tenant service account.

              * Click **Select a role** and enter **Cloud KMS CryptoKey Encrypter/Decrypter**.

              Click **SAVE**. Make a note of the key ring name.
      </Tab>
    </Tabs>

    ### Step 3. 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:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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).

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       <<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:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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:

       On a Mac, install JQ with `brew install jq`

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       cat cmek_config.json | jq
       ```

       After you have built your CMEK configuration manifest with the details of your cluster and provisioned the necessary cloud identity and encryption key, proceed to Step 4.

    ### Step 4. Activate CMEK

    Using the CockroachDB Cloud API, send a `POST` request with the contents of `cmek_config.json` to the cluster's `cmek` endpoint.

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    CLUSTER_ID= #{ your cluster ID }
    API_KEY= #{ your API key }
    curl --request POST \
      --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
      --header "Authorization: Bearer ${API_KEY}" \
      --header "content-type: application/json" \
      --data "@cmek_config.json"
    ```
  </Accordion>

  <Accordion title="Azure">
    ### Before you begin

    1. Find your CockroachDB Advanced cluster's ID. From the CockroachDB Cloud console [Clusters list](https://cockroachlabs.cloud/clusters), click the name of a cluster to open its **Cluster Overview** page. From the page's URL make a note of the part of the URL between `cluster/` and `/overview`. This is the cluster ID.
    2. Make a note of your Azure tenant ID. You can find this in the Azure portal under **Azure Active Directory** > **Overview** > **Tenant information**.

    ### Step 1. Set up Azure identity and permissions

    1. Use the CockroachDB Cloud API to get your cluster's identity ID:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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}"
       ```
    2. In the response, find the `azure_cluster_identity_client_id` field and store its value for a future step.
    3. Navigate to the following URL in your browser, replacing the placeholders with your values:

       ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       https://login.microsoftonline.com/{YOUR_TENANT_ID}/adminconsent?client_id={CLUSTER_IDENTITY_ID}
       ```
    4. Sign in with your Azure administrator credentials.
    5. Review the requested permissions ("Sign in and read user profile") and click **Accept**.

    This creates an enterprise application in your Azure tenant that CockroachDB Cloud can use to access your Key Vault. It is named using the following format:

    ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    CockroachDB Cloud - <CLUSTER_ID>
    ```

    ### Step 2. Create the CMEK key

    If you intend to use an existing key as the CMEK, skip this step.

    For these instructions, you can use an existing Azure Key Vault, or create a new key vault using the [Azure portal](https://learn.microsoft.com/azure/key-vault/general/quick-create-portal) or [CLI](https://learn.microsoft.com/azure/key-vault/general/quick-create-cli).

    1. In the Azure portal, navigate to your Key Vault.
    2. On the Key Vault left-hand sidebar, select **Objects** then select **Keys**.
    3. **Select + Generate/Import**.
    4. Enter a **Name** for the key, and click **Create**.
    5. Click the key name, and under Current Version, click the key.
    6. In the **Key Identifier** field, click the copy button. The URL will use the following format. Store it for a future step.

       ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       https://<keyVaultName.vault.azure.net/keys/<keyName/<version
       ```
    7. Navigate to your Key Vault > **Access control (IAM)** > **Add role assignment**.
    8. Select the **Key Vault Crypto Officer** role, and select the option to assign access to **User, group, or service principal**.
    9. Click **Select members**, then search for the enterprise application created above: `CockroachDB Cloud - <CLUSTER_ID>`.

    ### Step 3. 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. Create a new file named `cmek_config.json` with the following contents. 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.

       ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       {
         "region_specs": [
           {
             "region": "{COCKROACHDB_CLOUD_REGION}",
             "key_spec": {
               "type": "AZURE_KEY_VAULT",
               "uri": "{YOUR_KEY_IDENTIFIER_URL}",
               "auth_principal": "{YOUR_TENANT_ID}"
             }
           }
         ]
       }
       ```

       Replace the placeholder values:

       * <code>{'{COCKROACHDB_CLOUD_REGION}'}</code>: Your cluster's region (e.g., "centralindia")
       * <code>{'{YOUR_KEY_IDENTIFIER_URL}'}</code>: The Key Identifier URL you copied in Step 2
       * <code>{'{YOUR_TENANT_ID}'}</code>: Your Azure tenant ID

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

       On a Mac, install JQ with `brew install jq`

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       cat cmek_config.json | jq
       ```

       After you have built your CMEK configuration manifest with the details of your cluster and provisioned the necessary cloud identity and encryption key, proceed to Step 4.

    ### Step 4. Activate CMEK

    Using the CockroachDB Cloud API, send a `POST` request with the contents of `cmek_config.json` to the cluster's `cmek` endpoint.

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    CLUSTER_ID= #{ your cluster ID }
    API_KEY= #{ your API key }
    curl --request POST \
      --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
      --header "Authorization: Bearer ${API_KEY}" \
      --header "content-type: application/json" \
      --data "@cmek_config.json"
    ```
  </Accordion>
</AccordionGroup>

## Check CMEK status

To view your cluster's CMEK status, send a `GET` request:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \
  --header "Authorization: Bearer ${API_KEY}"
```

## Rotate a CMEK key

You can rotate a CMEK key for a CockroachDB Advanced cluster either by creating a new version of the existing CMEK key or by creating a new CMEK key. At a high level:

**To begin using a new version of an existing CMEK key**:

1. In your KMS platform, either configure automatic rotation for the CMEK key or perform a manual rotation.
2. CockroachDB Cloud does not automatically re-encrypt the store key using the new CMEK key version. For each region you want to update, perform a rotation without modifying the CMEK key URI. CockroachDB Cloud re-encrypts the store key using the new CMEK key version.

**To begin using an entirely new CMEK key**:

1. Within your KMS platform, create a new CMEK key.
2. Next, perform a rotation in CockroachDB Cloud and provide the new CMEK key URI.

Within your KMS, **do not** revoke access to, disable, schedule for destruction, or destroy a CMEK after it is rotated. It is still required to access data that was written using it. that is in use by one or more clusters. The CMEK is an external resource and is never stored in CockroachDB Cloud. If the CMEK for a cluster or region is not available in your KMS, nodes that are configured to use it cannot rejoin the cluster if they are restarted, and the cluster's managed CockroachDB Cloud backups will fail. Even if access to the CMEK is restored, affected nodes cannot automatically recover. For assistance in that situation, contact your Cockroach Labs account team.

To rotate a CMEK key:

1. Edit or recreate the cluster's `cmek_config.json` to update the `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.
2. Using the CockroachDB Cloud API, send a `PUT` request with the contents of `cmek_config.json` to the cluster's `cmek` endpoint:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CLUSTER_ID= #{ your cluster ID }
   API_KEY= #{ your API key }
   curl --request PUT \
     --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "content-type: application/json" \
     --data "@cmek_config.json"
   ```

## Add a region to a CMEK-enabled cluster

To add a region to a cluster that already has CMEK enabled:

1. Edit or recreate the cluster's `cmek_config.json` to update the `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.
2. Send the payload as a `PATCH` request to the cluster endpoint:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CLUSTER_ID= #{ your cluster ID }
   API_KEY= #{ your API key }
   curl --request PATCH \
     --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID} \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "content-type: application/json" \
     --data "@cmek_config.json"
   ```

## Revoke CMEK for a cluster

When you revoke access to the CMEK in your KMS, CockroachDB Cloud can no longer encrypt or decrypt your cluster's data. All access to the cluster's data will be prevented until you you restore access. In general, revoke access to the CMEK only when you are permanently decommissioning the cluster or to mitigate a critical security breach or at the request of Cockroach Labs support.

Within your KMS platform, you can revoke access to the CMEK temporarily or permanently.

Within your KMS, **do not revoke** access to a CMEK that is in use by one or more clusters. The CMEK is an external resource and is never stored in CockroachDB Cloud.

1. In your cloud provider's KMS platform, revoke CockroachDB Cloud's access to your CMEK key at the IAM level, either by removing the authorization the cross-account IAM role or by removing the cross-account IAM role's permission to access the key.

This will **not** immediately stop your cluster from encrypting and decrypting data, which does not take effect until you update your cluster in the next step. That is because CockroachDB does not use your CMEK key to encrypt/decrypt your cluster data itself. CockroachDB Advanced accesses your CMEK key to encrypt/decrypt a key encryption key (KEK). This KEK is used to encrypt a data encryption key (DEK), which is used to encrypt/decrypt your application data. Your cluster will continue to use the already-provisioned DEK until you make the Cloud API call to revoke CMEK.

1. Your cluster will continue to operate with the CMEK until you update it to revoke CMEK. To revoke access:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   curl --request PATCH \
     --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "content-type: application/json" \
     --data '{"action":"REVOKE"}'
   ```
2. [Check your CMEK status](#check-cmek-status) to confirm the revocation has taken effect.
3. Once you have resolved the security incident, re-authorize CMEK for your cluster to return to normal operations. Contact your account team, or [create a support ticket](https://support.cockroachlabs.com/).