DOC-14243-Cluster-Management#4127
Open
supritha-kumar wants to merge 13 commits into
Open
Conversation
sarahlwelton
requested changes
Jun 16, 2026
sarahlwelton
left a comment
sarahlwelton
left a comment
Contributor
There was a problem hiding this comment.
I'm not going to review all of this right now as I feel I'm addressing a lot of the same issues throughout, and I don't want to overwhelm with comments.
I can keep going if you like, but this needs a lot of work from a style and a content architecture position. There's some weird formatting decisions being made here, too.
Comment on lines
+108
to
+115
| **** xref:learn:security/per-node-per-bucket.adoc[Per-Node, Per-Bucket, and Per-Data-Type Encryption] | ||
| **** xref:learn:security/transparent-encryption-decryption.adoc[Transparent Encryption and Decryption] | ||
| **** xref:learn:security/master-password-encryption-at-rest.adoc[Master Password Encryption at Rest] | ||
| **** xref:learn:/security/encryption-key-management-services.adoc[Encryption Key Management Services] | ||
| **** xref:learn:security/multiple-KMS-multiple-keys.adoc[Multiple KMSs and Multiple Keys] | ||
| **** xref:learn:security/encryption-key-rotation-and-expiration.adoc[Encryption Key Rotation and Expiration] | ||
| **** xref:learn:security/when-CBServer-encrypts-data.adoc[When Couchbase Server Encrypts Data] | ||
| **** xref:learn:security/key-health-monitoring-alerts.adoc[Key Health Monitoring and Alerts] |
Contributor
There was a problem hiding this comment.
Do you want all of these to be at the same level as "Encryption Keys" in the nav?
| @@ -0,0 +1,395 @@ | |||
| [#keys] | |||
Contributor
There was a problem hiding this comment.
I don't think you really need to set a direct link on the title of a page? Why is it an H2 heading anyway?
|
|
||
| * *Audits:* As with configuration and log data, you can choose to use an encryption-at-rest key or the master password to encrypt audit data. | ||
|
|
||
| * *Other:* You can enable a key to encrypt service-generated data, such as Query Service temporary spill files. |
Contributor
There was a problem hiding this comment.
Can we call this "service-generated data" instead of "other," then?
| === Key Encryption Keys (KEKs) | ||
| You create and manage KEKs through the Couchbase Server REST API or UI. | ||
| A KEK encrypts and decrypts 1 or more Data Encryption Keys. | ||
| You can store a KEK locally (managed by Couchbase Server) or in an external KMS such as AWS KMS, Azure Key Vault, GCP KMS, HashiCorp Vault, or a KMIP-compatible server. |
Contributor
There was a problem hiding this comment.
Can we link to more info about each of these key vaults?
| Doing so causes Couchbase Server to call the external KMS for every DEK decryption, which increases latency and creates an availability dependency. | ||
| See <<remote-kms-best-practice>> for more information. | ||
|
|
||
| == Encrypting Bucket Data |
Contributor
There was a problem hiding this comment.
Can we link to this from where we talk about bucket encryption further up the page?
Comment on lines
+70
to
+83
| Before you configure an AWS KMS encryption key in Couchbase Server, complete the following steps in AWS: | ||
|
|
||
| . Create a symmetric encryption key in AWS KMS. | ||
| Record the key's Amazon Resource Name (ARN). | ||
|
|
||
| . Create an IAM user or role with the following minimum permissions on the key: | ||
| + | ||
| -- | ||
| * `kms:Encrypt` | ||
| * `kms:Decrypt` | ||
| * `kms:DescribeKey` | ||
| -- | ||
|
|
||
| . Generate an access key ID and secret access key for the IAM user (or configure an instance profile if running on EC2). |
Contributor
There was a problem hiding this comment.
Okay, but then we don't link to or explain how to set up the AWS KMS anyway?
|
|
||
| === Integration with Couchbase Server | ||
|
|
||
| When you create an encryption-at-rest key using the AWS KMS provider, you supply the following: |
Contributor
There was a problem hiding this comment.
Is this what Couchbase Server needs to set up AWS as a KMS? Shouldn't this still be prerequisites?
Comment on lines
+150
to
+165
| When you create an encryption-at-rest key using the GCP Cloud KMS provider, you supply the following: | ||
|
|
||
| [cols="1,2"] | ||
| |=== | ||
| | Parameter | Description | ||
|
|
||
| | `keyResourceName` | ||
| | The full resource name of the Cloud KMS key (for example, `projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key`). | ||
|
|
||
| | `credentialsFile` | ||
| | The path to the JSON service account key file on each Couchbase Server node. | ||
| Not required if you use instance-attached service account credentials. | ||
| |=== | ||
|
|
||
| NOTE: Place the service account key file on every node in the cluster at the same path. | ||
| Couchbase Server reads this file to authenticate with Cloud KMS. |
Contributor
There was a problem hiding this comment.
But then we don't have a considerations section here, and again, these aren't steps for configuring with this specific service and we don't link to these steps?
Comment on lines
+489
to
+490
| [#bring-your-own-key] | ||
| == Bring-Your-Own-Key (BYOK) |
Contributor
There was a problem hiding this comment.
This is significant enough and, I imagine, enough of a different workflow that it might be worth putting into a separate topic?
Again, this is a huge page and we could probably make it easier to navigate with tabs.
|
|
||
|
|
||
| [#aws-kms-caution] | ||
| == Remote KMS Best Practice |
Contributor
There was a problem hiding this comment.
Again, might be better as a separate page.
Contributor
Author
Hey Sarah, thank you for taking the time to review. A lil unsure why you got around to it despite me clearly calling out that I haven't had the time to do a self-review and changes still need to be made. |
self review + engg review
self review + engg review
self review + engg review
self review and engg reviews
self review and Engg review
self review and engg review
self review and engg review
self review and engg review
self review and engg review
self review and engg review
There was a problem hiding this comment.
Pull request overview
This PR adds and reorganizes documentation for native Encryption at Rest (including key management providers, operational procedures, and conceptual overviews) and wires the new content into the main navigation.
Changes:
- Expanded the Learn > Security > Encryption navigation with new Encryption at Rest subtopics.
- Split/manage Encryption at Rest operational guidance into dedicated Manage pages (encrypting data, rotating keys, dropping DEKs).
- Added new Learn pages covering key hierarchy concepts, KMS providers, rotation/expiration, monitoring, and transparency/performance.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 23 comments.
Show a summary per file
| File | Description |
|---|---|
| modules/ROOT/nav.adoc | Adds new Learn/Manage nav entries for Encryption at Rest topics. |
| modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc | Updates KMS provider list and restructures/create-key guidance. |
| modules/manage/pages/manage-security/encrypt-data-at-rest.adoc | New Manage procedure page for enabling encryption for buckets/system data. |
| modules/manage/pages/manage-security/manually-rotate-encryption-atrest-keys.adoc | New Manage procedure page for manual key rotation across providers. |
| modules/manage/pages/manage-security/manually-drop-DEKs-reencrypt-data.adoc | New Manage procedure page for drop-DEKs re-encryption and key deletion. |
| modules/learn/pages/security/native-encryption-at-rest-overview.adoc | Reworks the feature overview (what’s protected, comparisons, availability). |
| modules/learn/pages/security/encryption-at-rest-keys.adoc | New Learn page explaining KEK/DEK hierarchy and key usage concepts. |
| modules/learn/pages/security/encryption-key-management-services.adoc | New Learn reference describing supported KMS providers and best practices. |
| modules/learn/pages/security/multiple-KMS-multiple-keys.adoc | New Learn page describing multi-KMS architectures and rotation behavior. |
| modules/learn/pages/security/encryption-key-rotation-expiration.adoc | New Learn page detailing rotation vs re-encryption and operational impacts. |
| modules/learn/pages/security/when-CBServer-encrypts-data.adoc | New Learn page explaining encryption timing/states and enable/disable behavior. |
| modules/learn/pages/security/per-node-per-bucket.adoc | New Learn page describing per-node/per-bucket/per-data-type principles. |
| modules/learn/pages/security/transparent-encryption-decryption.adoc | New Learn page describing transparent read/write paths and performance notes. |
| modules/learn/pages/security/master-password-encryption-at-rest.adoc | New Learn page covering master password role, setup, and rotation. |
| modules/learn/pages/security/key-health-monitoring-alerts.adoc | New Learn page describing testing, alerts, metrics, and diagnostics. |
Comments suppressed due to low confidence (2)
modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc:60
- These xrefs point to
native-encryption-at-rest-overview.adoc#kmsand#keys, but that overview page no longer defines those anchors in this PR. As a result, both links will be broken.
See xref:learn:security/native-encryption-at-rest-overview.adoc#kms[Encryption Key Management Services] for more information.
You must decide what data your encryption key can encrypt.
You can create an encryption key that can encrypt any type of data and other encryption keys.
You can also choose to limit what types of data the key can encrypt, or configure it to only encrypt other encryption keys.
See xref:learn:security/native-encryption-at-rest-overview.adoc#keys[Encryption-at-Rest Keys] for more information.
modules/learn/pages/security/per-node-per-bucket.adoc:76
- This xref points to
manage-security/manage-encryption-at-rest.adoc, but that page does not exist. It also has a trailing space before the period. This will render as a broken link.
configuration, log, and audit data (in the `info` field).
For more information, see xref:manage:manage-security/manage-encryption-at-rest.adoc[Manage Native Encryption at Rest] .
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+111
to
+114
| **** xref:learn:/security/encryption-key-management-services.adoc[Encryption Key Management Services] | ||
| **** xref:learn:security/multiple-KMS-multiple-keys.adoc[Multiple KMSs and Multiple Keys] | ||
| **** xref:learn:security/encryption-key-rotation-and-expiration.adoc[Encryption Key Rotation and Expiration] | ||
| **** xref:learn:security/when-CBServer-encrypts-data.adoc[When Couchbase Server Encrypts Data] |
Comment on lines
+183
to
+185
| *** xref:manage:manage-security/encrypt-data-at-rest.adoc[Encrypt Data at Rest] | ||
| *** xref:manage:manage-security/manually-drop-DEKs-reencrypt-data.adoc[Manually Drop DEKs to Re-Encrypt Data] | ||
| *** xref:manage:manage-security/manage-encryption-at-rest-keys.adoc[Manage Encryption Keys] |
Comment on lines
45
to
+48
| For each key you create, you must choose a Key Management Service (KMS) that maintains the key for you. | ||
| You have three options to choose from: | ||
| You have 3 options to choose from: | ||
|
|
||
| * Amazon's AWS KMS | ||
| * Amazon Web Services Key Management Service (AWS KMS) |
Comment on lines
+1
to
+2
| == Encrypt Data at Rest | ||
| :description: pass:q[Once you have created an encrytion-at-rest key, you can use it to encrypt bucket data.] |
Comment on lines
+10
to
+12
| For audit, configuration, and log data, you can use the primary password or an encryption-at-rest key. Choose based on your security and operational requirements. | ||
| You must set the master password on each node before using it for encryption at rest. | ||
| By default, the nodes do not have a master password. |
Comment on lines
+57
to
+71
| Independent key rotation:: | ||
| You can rotate KEKs and DEKs independently. | ||
| Couchbase Server automatically rotates DEKs at a configurable interval without contacting the external KMS for each rotation. | ||
| <<encryption-key-rotation-and-expiration>> for more information. | ||
|
|
||
| Granular data isolation:: | ||
| You can assign different KEKs to different data types. | ||
| For example, you can use 1 KEK for bucket data and a different KEK for configuration data. | ||
| In multi-tenant configurations, each tenant's bucket can use its own KEK. | ||
| <<using-multiple-kmss-and-multiple-keys>> for more information. | ||
|
|
||
| IMPORTANT: Use an external KMS key only as a KEK for locally managed keys. | ||
| Do not assign an external KMS key directly to encrypt data. | ||
| Doing so causes Couchbase Server to call the external KMS for every DEK decryption, which increases latency and creates an availability dependency. | ||
| <<remote-kms-best-practice>> for more information. |
Comment on lines
+1
to
+3
| [#when-data-is-encrypted] | ||
| == When Couchbase Server Encrypts Data | ||
| :description: When you enable encryption at rest for a bucket or a type of system data, Couchbase Server encrypts all of the data it writes. However, it does not encrypt existing data in the bucket or already written system data. |
Comment on lines
+13
to
+16
| You can use the REST API to force Couchbase Server to encrypt existing unencrypted data. | ||
| See xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc[] for more information. | ||
|
|
||
| See xref:manage:manage-security/manage-encryption-at-rest.adoc#force-encryption[Force Encryption of Unencrypted Data] for more information. |
Comment on lines
+57
to
+60
| You can check the encryption state using the `cm_encr_at_rest_data_status` metric or the REST API status endpoints. | ||
|
|
||
|
|
||
| See <<key-health-monitoring>> for more information. |
Comment on lines
+19
to
+23
| Using multiple KMSs means you have multiple availability dependencies. | ||
|
|
||
| * Use the <<remote-kms-best-practice,recommended multi-layer architecture>> for each external KMS. | ||
| Assign external keys only as KEKs for locally managed keys — not directly to encrypt data. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sub branch for documenting Cluster Management