DOC-14243-Cluster-Management - #4127
Conversation
sarahlwelton
left a comment
sarahlwelton
left a comment
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.
| **** 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] |
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] | |||
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. |
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. |
There was a problem hiding this comment.
Can we link to more info about each of these key vaults?
| 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). |
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: |
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?
| 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. |
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?
| [#bring-your-own-key] | ||
| == Bring-Your-Own-Key (BYOK) |
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 |
There was a problem hiding this comment.
Again, might be better as a separate page.
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.
Sub branch for documenting Cluster Management