Couchbase Encryption At Rest

How to configure Couchbase Server with encryption at rest. This guide covers operator-managed keys, AWS KMS-backed keys, and KMIP-backed keys,

Couchbase Server supports encryption at rest. This is a feature that allows you to encrypt the data at rest on the disk.

Prerequisites

Couchbase Server 8.0.0 or later

Overview

In Couchbase 8.0.0 Encryption at Rest was introduced which allows data on the Couchbase Nodes to be encrypted at rest. The data that can be encrypted at rest includes:

Data in buckets
Cluster configuration
Logs
Audit

Couchbase offers three types of Keys that can be used to encrypt data:

Couchbase Server Managed Keys
AWS KMS Keys
KMIP Keys

Enabling Encryption at Rest Management

To use any Encryption at Rest features through the Operator, you must first enable encryption at rest management on the Couchbase Cluster resource.

apiVersion: couchbase.com/v2
kind: CouchbaseCluster
metadata:
  name: my-cluster
spec:
  security:
    encryptionAtRest:
      managed: true (1)

1	Enable operator-managed encryption at rest. By default, this is disabled.

Once enabled, the operator will manage encryption keys and apply encryption settings to your cluster.

Selecting Encryption Keys

By default, the operator will use all CouchbaseEncryptionKey resources in the same namespace as the cluster. You can use a label selector to control which keys the operator manages:

apiVersion: couchbase.com/v2
kind: CouchbaseCluster
metadata:
  name: my-cluster
spec:
  security:
    encryptionAtRest:
      managed: true
      selector: (1)
        matchLabels:
          cluster: my-cluster

1	Only encryption keys with the label `cluster: my-cluster` will be managed for this cluster.

Managing Couchbase Server Managed Keys

Couchbase Server Managed Keys (also called AutoGenerated keys) are the simplest type of encryption key. These keys are generated and managed automatically by Couchbase Server without requiring external key management services.

Basic Example

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-key
spec:
  keyType: AutoGenerated

Usage

Keys can be used to encrypt different types of data, and this usage can be enforced by setting the usage of the key. Setting the usage of the key restricts what it can be be used to encrypt, with the options being:

Keys
Configuration
Logs
Audit
Buckets

By default keys can be used to encrypt anything. To restrict the usage of the key the spec.usage object on the key can be used to set the usage of the key.

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-key
spec:
  keyType: AutoGenerated
  usage:
    configuration: true (1)
    key: true (2)
    log: true (3)
    audit: true (4)
    allBuckets: true (5)

1	The `spec.usage.configuration` field defines whether the key should be used for configurations. This is set to true by default.
2	The `spec.usage.key` field defines whether the key should be used for keys. This is set to true by default.
3	The `spec.usage.log` field defines whether the key should be used for logs. This is set to true by default.
4	The `spec.usage.audit` field defines whether the key should be used for audit. This is set to true by default.
5	The `spec.usage.allBuckets` field defines whether the key should be used for all buckets. This is set to true by default.

Additional Options

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-key
spec:
  keyType: AutoGenerated
  autoGenerated:
    rotation:
      intervalDays: 30 (1)
      StartTime: 2025-01-01T00:00:00Z (2)
    canBeCached: true

1	The `spec.autoGenerated.rotation.intervalDays` field defines the interval in days at which the key should be rotated.
2	The `spec.autoGenerated.rotation.startTime` field defines the first time at which the key rotation will start.

Key Encryption with Another Key

For enhanced security, AutoGenerated keys can be encrypted with another encryption key instead of the cluster’s master password:

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: master-key
spec:
  keyType: AutoGenerated
  usage: (1)
    configuration: false
    key: true (2)
    log: false
    audit: false
    allBuckets: false
---
apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: bucket-key
spec:
  keyType: AutoGenerated
  autoGenerated:
    encryptWithKey: master-key (3)
  usage:
    configuration: false
    key: false
    log: false
    audit: false
    allBuckets: true (4)

1	Restrict the master key’s usage to only encrypt other keys (Key Encryption Key).
2	Allow this key to be used for encrypting other keys.
3	Encrypt this key using the `master-key` encryption key.
4	This key will only be used to encrypt bucket data.

Managing AWS KMS Keys

AWS Key Management Service (KMS) is a fully managed service that makes it easy to create, manage, and control cryptographic keys used to protect your data. AWS KMS Keys can be used to encrypt the data at rest in the Couchbase Cluster. To use AWS KMS Keys you will need to provide a way to authenticate with AWS, either using IMDS or providing a secret with credentials.

Prerequisites

An AWS account with KMS key creation permissions
A KMS key created in AWS
Either:
- AWS credentials with permission to use the KMS key, or
- IAM role attached to the Kubernetes nodes with KMS permissions (for IMDS)

Basic Example with AWS Credentials

To provide AWS credentials via a Kubernetes secret a secret with the AWS credentials must be created. The credentials file should follow the standard AWS credentials format:

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

The secret can be created using the following command:

Step 1: Create an AWS credentials secret

kubectl create secret generic aws-credentials \
  --from-file=credentials=/path/to/.aws/credentials

Step 2: Create the encryption key resource

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-aws-key
spec:
  keyType: AWS (1)
  awsKey:
    keyARN: "arn:aws:kms:us-east-1:123456789012:key/abcd1234-ab12-cd34-ef56-abcdef123456" (2)
    keyRegion: "us-east-1" (3)
    credentialsSecret: "aws-credentials" (4)
    profileName: <optional profile name> (5)

1	Specifies that this is an AWS KMS key.
2	The ARN of your KMS key from AWS.
3	The AWS region where the KMS key is located.
4	The name of the Kubernetes secret containing AWS credentials.
5	The optional profile name to use for the AWS credentials if multiple profiles are present in the credentials file.

Authenticating with IMDS

When running in AWS (EKS or Kubernetes on EC2), you can use Instance Metadata Service (IMDS) to authenticate using the IAM role attached to the nodes:

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-aws-key-imds
spec:
  keyType: AWS
  awsKey:
    keyARN: "arn:aws:kms:us-east-1:123456789012:key/abcd1234-ab12-cd34-ef56-abcdef123456"
    keyRegion: "us-east-1"
    useIMDS: true (1)

1	Enable authentication using IMDS. No credentials secret is required.

Managing KMIP Keys

Key Management Interoperability Protocol (KMIP) is an OASIS standard for communication between key management systems and applications. KMIP allows you to use external key management solutions from vendors like Thales, IBM, or HashiCorp Vault.

Prerequisites

A KMIP-compliant server
Client certificate and private key in PKCS#8 format
KMIP server host and port
A key ID for an existing key on the KMIP server

Basic Example

Step 1: Create a Kubernetes secret with client credentials

apiVersion: v1
kind: Secret
metadata:
  name: kmip-client-secret
type: Opaque
data:
  passphrase: <passphrase base64 encoded>
  tls.key: <tls-key base64 encoded>
  tls.crt: <tls-crt base64 encoded>

The secret must contain three keys :

tls.crt - The client certificate
tls.key - The client private key in encrypted PKCS#8 format
passphrase - The passphrase for decrypting the private key

Step 2: Create the KMIP encryption key resource

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-kmip-key
spec:
  keyType: KMIP (1)
  kmipKey:
    host: "kmip.example.com" (2)
    port: 5696 (3)
    timeoutInMs: 5000 (4)
    clientSecret: "kmip-client-cert" (5)
    verifyWithSystemCA: true (6)
    verifyWithCouchbaseCA: true (7)
    keyID: "existing-key-identifier" (8)

1	Specifies that this is a KMIP-managed key.
2	The hostname of your KMIP server.
3	The port number of your KMIP server (standard KMIP port is 5696).
4	Connection timeout in milliseconds (must be between 1000 and 300000).
5	The name of the Kubernetes secret containing client certificates.
6	Verify the KMIP server certificate against the system CA bundle.
7	Verify the KMIP server certificate against the Couchbase CA bundle.
8	The unique identifier of the existing key in the KMIP server.

Encryption Approaches

KMIP supports two encryption approaches:

apiVersion: couchbase.com/v2
kind: CouchbaseEncryptionKey
metadata:
  name: my-kmip-key-native
spec:
  keyType: KMIP
  kmipKey:
    host: "kmip.example.com"
    port: 5696
    timeoutInMs: 5000
    clientSecret: "kmip-client-cert"
    encryptionApproach: NativeEncryptDecrypt (1)

1	Use native encrypt/decrypt operations on the KMIP server.

Available approaches:

LocalEncrypt (default) - Key material is retrieved and encryption/decryption happens locally on Couchbase nodes. Better performance.
NativeEncryptDecrypt - Encryption/decryption operations are performed by the KMIP server. Key material never leaves the KMIP server. More secure but higher latency.

Choose NativeEncryptDecrypt when security requirements mandate that key material never leaves the key management system. Choose LocalEncrypt for better performance when the security model allows it.

Encrypting Cluster Data

Once encryption keys are created, you can enable encryption for different types of cluster data.

Encrypting Configuration, Logs, and Audit

Configuration, logs, and audit logs can be encrypted at the cluster level:

apiVersion: couchbase.com/v2
kind: CouchbaseCluster
metadata:
  name: my-cluster
spec:
  security:
    encryptionAtRest:
      managed: true
      configuration: (1)
        enabled: true
        keyName: "my-autogen-key" (2)
        keyLifetime: "8760h" (3)
        rotationInterval: "720h" (4)
      audit: (5)
        enabled: true
        keyName: "my-autogen-key"
        keyLifetime: "8760h"
        rotationInterval: "720h"
      log: (6)
        enabled: true
        keyName: "my-autogen-key"
        keyLifetime: "8760h"
        rotationInterval: "720h"

1	Enable encryption for cluster configuration.
2	Use the `my-autogen-key` encryption key. If not specified, the cluster master password is used.
3	Data Encryption Key (DEK) lifetime in hours. Default is 8760 hours (1 year). Must be at least 720 hours (30 days).
4	DEK rotation interval in hours. Default is 720 hours (30 days). Must be at least 168 hours (7 days).
5	Enable encryption for audit logs.
6	Enable encryption for log files.

Enabling encryption for log files will break fluent-bit log streaming, as the logs will be encrypted and unreadable by the log collector. Only enable log encryption if you don’t rely on log streaming.

Using Default Encryption (Master Password)

You can enable encryption without specifying a key name. In this case, the cluster’s master password is used:

apiVersion: couchbase.com/v2
kind: CouchbaseCluster
metadata:
  name: my-cluster
spec:
  security:
    encryptionAtRest:
      managed: true
      configuration:
        enabled: true (1)
        # keyName not specified - uses master password

1	Encrypt configuration using the cluster master password instead of an encryption key.

Encrypting Buckets

Individual buckets can be encrypted with specific keys. This is configured at the bucket level:

apiVersion: couchbase.com/v2
kind: CouchbaseBucket
metadata:
  name: my-encrypted-bucket
spec:
  name: my-encrypted-bucket
  memoryQuota: 512Mi
  encryptionAtRest: (1)
    keyName: "my-autogen-key" (2)
    keyLifetime: "8760h" (3)
    rotationInterval: "720h" (4)

1	Enable bucket encryption.
2	The encryption key to use.
3	DEK lifetime. Default is 8760 hours (1 year).
4	DEK rotation interval. Default is 720 hours (30 days).