---
title: Couchbase Encryption At Rest
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbase/docs-operator/edit/release/2.9/modules/ROOT/pages/tutorial-encryption-at-rest.adoc
  xref: xref:operator::tutorial-encryption-at-rest.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/operator/current/tutorial-encryption-at-rest.html)

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

* Couchbase Server 8.0.0 or later

## [](#overview)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)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.

```yaml
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)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:

```yaml
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)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)Basic Example

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

### [](#usage)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.

```yaml
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)Additional Options

```yaml
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)Key Encryption with Another Key

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

```yaml
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)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-2)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)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:

```ini
[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

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

Step 2: Create the encryption key resource

```yaml
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)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:

```yaml
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)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-3)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-2)Basic Example

Step 1: Create a Kubernetes secret with client credentials

```yaml
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

```yaml
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)Encryption Approaches

KMIP supports two encryption approaches:

```yaml
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)Encrypting Cluster Data

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

### [](#encrypting-configuration-logs-and-audit)Encrypting Configuration, Logs, and Audit

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

```yaml
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.                                                                                   |

> [!WARNING]
> 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)Using Default Encryption (Master Password)

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

```yaml
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)Encrypting Buckets

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

```yaml
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). |