Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Use Customer-Managed Encryption Keys (CMEK) at Rest

  • Capella Operational
  • how-to
    +
    Capella encrypts cluster volumes at rest. You can move control of the keys from Couchbase to your own key management system (KMS).

    By default, all clusters in Couchbase Capella use your cluster’s cloud provider KMS to encrypt cluster volumes at rest. Instead of using this Couchbase-managed solution, you can create your own encryption keys for data at rest using customer-managed encryption keys (CMEK). By managing your encryption keys, you control their configuration, rotation cycles, geographic storage location, and can directly revoke them.

    Customer-managed encryption keys for bucket backups are not available at this time. To manage your encryption keys for a bucket backup, you can run your backup outside Capella. If you use CMEK on your cluster for encryption at rest, Capella encrypts your cluster backups with the same key used to encrypt your cluster storage.

    Do not delete a Key Management System (KMS) Key ID until any cluster backups using that Key ID have expired. If you delete the Key ID, your backup becomes unusable. Encryption Key IDs must be enabled and available to restore an encrypted backup to a Capella cluster.

    Key Management Provider Support

    Capella supports the following customer key management providers for encryption at rest:

    Couchbase recommends using one key per cluster and not sharing keys across clusters.

    Customer-managed encryption keys are available to clusters using the Enterprise plan.

    Configure Capella to use Customer Key Management

    To add and manage customer-managed encryption keys, you must use the Management API. Through the Management API, you can:

    • Add a customer-managed encryption key.

    • Get the details of a key based on its ID.

    • Get a list of keys created in an organization.

    • Rotate a key to replace an existing key with a new one.

    • Delete an existing key.

    • Associate a key with a cluster to enable encryption.

    • Disassociate a key with a cluster.

    For the details and requirements of each call, see the Management API v4.0 Reference. If you’re new to the Management API, see Get Started with the Management API v4.0

    Prerequisites

    • You must have the Organization Owner role to create, rotate, and delete customer-managed encryption keys. The Project Owner and Organizations Owner roles can associate a key with a cluster. All organization members can retrieve the list of keys in an organization and view the details of a key.

    • You have a Management API key.

    • You have deployed a cluster.

    AWS Requirements

    • A symmetric encryption key in AWS KMS that’s in the same region as your cluster.

    • The unique Capella AWS account ID that’s associated with your organization. Get this account ID by making a GET - Get Cloud Accounts call to the Couchbase Capella Management API.

      Use this account ID when adding CMEK to other AWS clusters in your organization.

    • A key policy with the following permissions:

      • DescribeKey

      • GenerateDataKeyWithoutPlainText

      • Decrypt

      • ReEncrypt*

      • CreateGrant with the kms:GrantIsForAWSResource condition set to the Capella AWS account ID associated with your organization.

      • The principal set to the Capella AWS account ID that’s associated with your organization.

        Example
        {
            "Sid": "Allow use of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<capella-account-id>:root"
            },
            "Action": [
                "kms:DescribeKey",
                "kms:GenerateDataKeyWithoutPlainText",
                "kms:Decrypt",
                "kms:ReEncrypt*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<capella-account-id>:root"
            },
            "Action": "kms:CreateGrant",
            "Resource": "*",
            "Condition": {
                "Bool": {
                    "kms:GrantIsForAWSResource": "true"
                }
            }
        }
        For more information about cross-account KMS encryption key access, see Creating KMS keys that other accounts can use

    • The Amazon Resource Name (ARN) of your KMS encryption key.

    GCP Requirements

    • A symmetric encryption key in GCP KMS.

    • The Key Version Resource ID of your GCP KMS encryption key.

    • The unique Capella Google service account ID that’s associated with your organization. Get this account ID by making a GET - Get Cloud Accounts call to the Couchbase Capella Management API.

      Use this service account ID when adding CMEK to other GCP clusters in your organization.

    • A service account on the key with the following permissions:

    Add a Customer-Managed Encryption Key

    This example uses AWS KMS, but the process for GCP is similar with resourceName used instead of arn in the payload.

    To add a customer-managed encryption key to your organization, make a POST - Create Key Metadata call to the Capella Management API. For example:

    • $ORGID is the organization ID.

    • $TOKEN is the API key token.

    • $ARN is the Amazon Resource Name (ARN) of the KMS encryption key.

    • $CMEKID is the Capella ID of the customer-managed encryption key.

    HTTP Request
    curl --request POST \
  --url "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORGID/cmek" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Key name",
  "description": "Description of the key",
  "config": {
	  "arn": "$ARN"
	  }
  }'
    HTTP Response
    {
    "id": "$CMEKID"
}

    Create a Cluster Using a Customer-Managed Encryption Key

    After adding a customer-managed encryption key, you can use this key when creating new clusters with the Management API. Do this by adding the cmekId field with the Capella ID of the customer-managed encryption key to the payload when creating a cluster.

    For more information, see POST - Create Cluster

    Apply a Customer-Managed Encryption Key to an Existing Cluster

    To apply a customer-managed encryption key to an existing cluster, make a POST - Associate Key with Cluster call to the Capella Management API. This call needs the ID of the cluster you want to apply the encryption to and the CMEK ID—​the Capella ID of the customer-managed encryption key you’re using.

    The CMEK ID is in the response when you add a new key, and you can retrieve it by making a GET - List Key Metadata call to the Capella Management API.

    When the POST - Associate Key with Cluster call is successful, the cluster rebalances to encrypt the existing data with the customer-provided key. Rebalancing does not cause any downtime.

    You can confirm that your cluster is using the encryption key by making a GET - Get Cluster call and finding cmekId in the response.

    Key Rotation

    Do not use key rotation in the cloud service provider. KMS encryption key expiry is not supported. Only rotate keys out of Capella and remove them from your key management provider once your cluster has a new KMS encryption key. If a customer-managed encryption key becomes unavailable, the related cluster experiences availability issues and data loss.

    Capella cannot rotate customer-managed encryption keys. You must do this using the Capella Management API.

    To rotate your customer-managed encryption keys:

    1. Create a new KMS encryption key in your cloud service provider.

    2. Make a PUT - Rotate Key call to the Capella Management API with the resource name of your new KMS encryption key.

      After associating a new key with your cluster, Capella rebalances all nodes in that cluster. Rebalancing does not cause any downtime. Only remove the old key from your key management provider once your cluster is using the new KMS encryption key.

    You can rotate customer-managed encryption keys once every 30 days. Contact Couchbase Support if you need to rotate keys earlier.

    See Also