DOC-13857 - Tutorial on how to detect AVX2 CPU Extension

antora.yml

@@ -1,6 +1,6 @@
 name: operator
 title: Kubernetes Operator
-version: '2.8'
+version: '2.9'
 prerelease: false
 start_page: ROOT:overview.adoc
 nav:

modules/ROOT/nav.adoc

@@ -37,6 +37,8 @@
   *** xref:concept-data-save-restore.adoc[Data Topology Save, Restore and Synchronization]
   *** xref:howto-guide-save-restore.adoc[How-to Guide: Data Topology Save and Restore]
   *** xref:howto-guide-data-topology-sync.adoc[How-to Guide: Data Topology Synchronization]
+** Data Encryption
+  *** xref:concept-encryption-at-rest.adoc[Encryption at Rest]
  ** Hibernation
   *** xref:concept-hibernation.adoc[Couchbase Cluster Hibernation]
  ** Logging
@@ -89,6 +91,7 @@
   *** xref:howto-manage-couchbase-logging.adoc[Manage Couchbase Logging]
   *** xref:howto-couchbase-log-forwarding.adoc[Configure Log Forwarding]
   *** xref:howto-non-root-install.adoc[Configure Non-Root Installs]
+  *** xref:howto-encryption-at-rest.adoc[Configure Encryption at Rest]
  ** Connect
   *** xref:howto-ui.adoc[Access the Couchbase User Interface]
   *** xref:howto-client-sdks.adoc[Configure Client SDKs]
@@ -132,6 +135,8 @@ include::partial$autogen-reference.adoc[]
  ** xref:tutorial-autoscale-query.adoc[Autoscaling Couchbase Query Service]
 * Backup
  ** xref:tutorial-velero-backup.adoc[Backup with VMware Velero]
+* Encryption at Rest
+ ** xref:tutorial-encryption-at-rest.adoc[Encryption at Rest]
 * Logging
  ** xref:tutorial-couchbase-log-forwarding.adoc[]
 * Monitoring
@@ -142,6 +147,8 @@ include::partial$autogen-reference.adoc[]
  ** xref:tutorial-kubernetes-network-policy.adoc[Kubernetes Network Policies Using Deny-All Default]
 * Persistent Volumes
  ** xref:tutorial-volume-expansion.adoc[Persistent Volume Expansion]
+* Scheduling
+ ** xref:tutorial-avx2-scheduling.adoc[AVX2-Aware Scheduling]
 * Sync Gateway
  ** xref:tutorial-sync-gateway.adoc[Connecting Sync-Gateway to a Couchbase Cluster]
  ** xref:tutorial-sync-gateway-clients.adoc[Exposing Sync-Gateway to Couchbase Lite Clients]

modules/ROOT/pages/concept-encryption-at-rest.adoc

@@ -0,0 +1,169 @@
+= Encryption At Rest
+:description: Understand encryption at rest in Couchbase Server and how to configure it using the Autonomous Operator.
+
+[abstract]
+{description}
+
+== Overview
+
+Encryption at rest is a security feature introduced in Couchbase Server 8.0.0 that protects your data by encrypting it on disk. When enabled, sensitive data stored on the Couchbase nodes is encrypted, ensuring that even if the underlying storage is compromised, the data remains secure.
+
+== What Data Can Be Encrypted?
+
+Encryption at rest supports encrypting multiple types of data within your Couchbase deployment:
+
+* *Data in buckets* - The actual documents and data stored in your buckets
+* *Cluster configuration* - Sensitive cluster settings and configurations
+* *Logs* - Server log files (note: encrypting logs will break fluent-bit log streaming)
+* *Audit logs* - Security audit trail data
+
+== Key Types
+
+Couchbase offers flexibility in how encryption keys are managed through three different key types:
+
+=== Couchbase Server Managed Keys
+
+Also called AutoGenerated keys, these are the simplest option. Couchbase Server automatically generates and manages these keys without requiring external services. This is ideal for:
+
+* Environments without external key management infrastructure
+* Use cases where key management can be handled within Couchbase
+
+=== AWS KMS Keys
+
+AWS Key Management Service (KMS) integration allows you to use AWS-managed encryption keys. This is recommended when:
+
+* Running Couchbase in AWS (EKS or EC2)
+* Your organization uses AWS KMS for centralized key management
+* You need compliance with AWS security standards
+
+=== KMIP Keys
+
+Key Management Interoperability Protocol (KMIP) is an industry standard that works with enterprise key management systems from vendors like Thales, IBM, or HashiCorp Vault. Choose KMIP when:
+
+* You have an existing enterprise key management system
+* You need vendor-neutral key management
+* Compliance requires external key management
+
+== Key Concepts
+
+=== Key Encryption Keys (KEK) and Data Encryption Keys (DEK)
+
+Couchbase uses a two-tier key hierarchy:
+
+* *Key Encryption Keys (KEK)* - The master keys you define through `CouchbaseEncryptionKey` resources. These encrypt other keys or data.
+* *Data Encryption Keys (DEK)* - Temporary keys generated by Couchbase to encrypt actual data. These are encrypted by KEKs.
+
+=== Key Rotation
+
+Key rotation is an important security practice. With encryption at rest:
+
+* KEK rotation can be scheduled through the `CouchbaseEncryptionKey` resource
+* DEK rotation happens automatically based on the `rotationInterval` setting
+* When a key rotates, new data is encrypted with the new key while old data remains accessible
+
+=== Key Usage Restrictions
+
+You can restrict what each key encrypts by setting usage parameters:
+
+* `configuration` - Cluster configuration data
+* `key` - Other encryption keys
+* `log` - Log files
+* `audit` - Audit logs
+* `allBuckets` - All bucket data
+
+By default, keys can encrypt anything. Restricting usage improves security through separation of concerns.
+
+== How to Enable Encryption At Rest
+
+Enabling encryption at rest with the Autonomous Operator involves three main steps:
+
+=== Step 1: Enable Encryption Management
+
+First, enable encryption at rest management on your `CouchbaseCluster` resource:
+
+[source,yaml]
+----
+apiVersion: couchbase.com/v2
+kind: CouchbaseCluster
+metadata:
+  name: my-cluster
+spec:
+  security:
+    encryptionAtRest:
+      managed: true
+----
+
+=== Step 2: Create Encryption Keys
+
+Create one or more `CouchbaseEncryptionKey` resources. Here's a simple example with an auto-generated key:
+
+[source,yaml]
+----
+apiVersion: couchbase.com/v2
+kind: CouchbaseEncryptionKey
+metadata:
+  name: my-key
+spec:
+  keyType: AutoGenerated
+----
+
+For AWS KMS or KMIP keys, additional configuration is required (see xref:tutorial-encryption-at-rest.adoc[]).
+
+=== Step 3: Apply Encryption to Data
+
+Configure which data should be encrypted on your cluster or buckets:
+
+[source,yaml]
+----
+apiVersion: couchbase.com/v2
+kind: CouchbaseCluster
+metadata:
+  name: my-cluster
+spec:
+  security:
+    encryptionAtRest:
+      managed: true
+      configuration:
+        enabled: true
+        keyName: "my-key"
+      audit:
+        enabled: true
+        keyName: "my-key"
+----
+
+For bucket-level encryption:
+
+[source,yaml]
+----
+apiVersion: couchbase.com/v2
+kind: CouchbaseBucket
+metadata:
+  name: secure-bucket
+spec:
+  name: secure-bucket
+  memoryQuota: 512Mi
+  encryptionAtRest:
+    keyName: "my-key"
+----
+
+== Security Considerations
+
+When implementing encryption at rest:
+
+* *Key Protection* - Consider encrypting your data keys with a dedicated Key Encryption Key (KEK) rather than using the cluster master password
+* *Key Rotation* - Implement regular key rotation schedules appropriate for your security requirements
+* *External Key Management* - For sensitive environments, consider using AWS KMS or KMIP instead of auto-generated keys
+* *Log Encryption Trade-offs* - Be aware that encrypting logs prevents log streaming to monitoring systems
+
+== Next Steps
+
+For detailed configuration instructions and advanced features, see:
+
+* xref:tutorial-encryption-at-rest.adoc[How to Configure Encryption At Rest] - Complete configuration guide with all options
+
+== Related Information
+
+* xref:concept-security.adoc[Security Concepts]
+* xref:howto-manage-buckets.adoc[Managing Buckets]
+* xref:howto-manage-cluster.adoc[Managing Clusters]
+

modules/ROOT/pages/concept-platform-certification.adoc

@@ -127,9 +127,9 @@ To submit the self-certification results to Couchbase, follow these steps:
 
 . Capture the Kubernetes platform's version information and other platform-specific components such as storage and networking.
 
-. To upload the results to Couchbase, you will need a JIRA account for Couchbase; you can request a JIRA account here: https://issues.couchbase.com/secure/ContactAdministrators!default.jspa.
+. If you are an existing customer of Couchbase, create a support ticket for instructions on how to submit your certification archive.
 
-. Create a new JIRA ticket, project - Couchbase Kubernetes (K8S), and Summary - [Operator Self-Certification Lifecycle].
+. If you are a new customer of Couchbase, contact your Couchbase Account Team or use our general https://www.couchbase.com/contact/[contact page].
 
 == Platform Requirements
 

modules/ROOT/pages/howto-xdcr.adoc

@@ -14,8 +14,8 @@ This page documents how to setup XDCR to replicate data to a different Kubernete
 In this scenario the remote cluster is accessible with Kubernetes based DNS.
 This applies to both xref:concept-couchbase-networking.adoc#intra-kubernetes-networking[intra-Kubernetes networking] and xref:concept-couchbase-networking.adoc#inter-kubernetes-networking-with-forwarded-dns[inter-Kubernetes networking with forwarded DNS].
 
-When using inter-Kubernetes networking, the local XDCR client must forward DNS requests to the remote cluster in order to resolve DNS names of the target Couchbase instances.
-Refer to the xref:tutorial-remote-dns.adoc[Inter-Kubernetes Networking with Forwarded DNS] tutorial to understand how to configure forwarding DNS servers.
+When using inter-Kubernetes networking, the local XDCR client must forward DNS requests to the remote cluster to resolve DNS names of the target Couchbase instances.
+For more information, see the xref:tutorial-remote-dns.adoc[Inter-Kubernetes Networking with Forwarded DNS] tutorial to understand how to configure forwarding DNS servers.
 
 TLS is optional with this configuration, but shown for completeness.
 To configure without TLS, omit any TLS related attributes.
@@ -56,10 +56,10 @@ spec:
   remoteBucket: destination
 ----
 
-<.> The resource is labeled with `replication:from-my-cluster-to-remote-cluster` to avoid any ambiguity because by default the Operator will select all `CouchbaseReplication` resources in the namespace and apply them to all remote clusters.
-Thus the label is specific to the source cluster and target cluster.
+<.> The resource is labeled with `replication:from-my-cluster-to-remote-cluster` to avoid any ambiguity because by default the Couchbase Autonomous Operator selects all `CouchbaseReplication` resources in the namespace and apply them to all remote clusters.
+The label is specific to the source cluster and target cluster.
 
-We define a remote cluster on our local resource:
+Define a remote cluster on the local resource:
 
 [source,yaml]
 ----
@@ -101,12 +101,12 @@ spec:
 <.> The correct hostname to use is the remote cluster's console service to provide stable naming and service discovery.
 The hostname is calculated as per the xref:howto-client-sdks.adoc#dns-based-addressing[SDK configuration how-to].
 
-<.> As we are not using client certificate authentication we specify a secret containing a username and password on the remote system.
+<.> As we're not using client certificate authentication, specify a secret containing a username and password on the remote system.
 
 <.> **TLS only:** For TLS connections you need to specify the remote cluster CA certificate in order to verify the remote cluster is trusted.
 xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-xdcr-remoteclusters-tls-secret[`couchbaseclusters.spec.xdcr.remoteClusters.tls.secret`] documents the secret format.
 
-<.> Replications are selected that match the labels we specify, in this instance the ones that go from this cluster to the remote one.
+<.> Replications are selected that match the labels specified, in this instance the ones that go from this cluster to the remote cluster.
 
 <.> **Inter-Kubernetes networking with forwarded DNS only:** the xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-servers-pod[`couchbaseclusters.spec.servers.pod.spec.dnsPolicy`] field tells Kubernetes to provide no default DNS configuration.
 
@@ -184,7 +184,7 @@ spec:
 ----
 
 <.> The resource is labeled with `replication:from-my-cluster-to-remote-cluster` to avoid any ambiguity because by default the Operator will select all `CouchbaseReplication` resources in the namespace and apply them to all remote clusters.
-Thus the label is specific to the source cluster and target cluster.
+The label is specific to the source cluster and target cluster.
 
 We define a remote cluster on our local resource:
 
@@ -217,18 +217,32 @@ spec:
 <.> The correct hostname to use is the remote cluster's console service to provide stable naming and service discovery.
 The hostname is calculated as per the xref:howto-client-sdks.adoc#dns-based-addressing-with-external-dns[SDK configuration how-to].
 
-<.> As we are not using client certificate authentication we specify a secret containing a username and password on the remote system.
+<.> As we're not using client certificate authentication, specify a secret containing a username and password on the remote system.
 
 <.> For TLS connections you need to specify the remote cluster CA certificate in order to verify the remote cluster is trusted.
 xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-xdcr-remoteclusters-tls-secret[`couchbaseclusters.spec.xdcr.remoteClusters.tls.secret`] documents the secret format.
 
-<.> Replications are selected that match the labels we specify, in this instance the ones that go from this cluster to the remote one.
+<.> Replications are selected that match the labels specified, in this instance the ones that go from this cluster to the remote cluster.
 
 == IP Based Addressing
 
-In this discouraged scenario, there is no shared DNS between two Kubernetes clusters - we must use IP based addressing.
+In this discouraged scenario, there is no shared DNS between 2 Kubernetes clusters - it must use IP based addressing.
 Pods are exposed by using Kubernetes `NodePort` type services.
-As there is no DNS, TLS is not supported, so security must be maintained between the two clusters using a VPN.
+As there is no DNS, TLS is not supported, so security must be maintained between the 2 clusters using a VPN.
+
+When you use NodePorts on a remote Couchbase cluster for XDCR connections, you risk interruptions if Kubernetes deletes and recreates the Service.
+Kubernetes does not guarantee that a new Service reuses the same NodePort.
+If the port number changes, XDCR connections that rely on the old IP:NodePort become invalid.
+
+The exact outcome depends on the Kubernetes CNI (Container Networking Interface) implementation.
+In some cases, Kubernetes removes the old port before it creates the new service, which causes a brief loss of connectivity.
+In other cases, Kubernetes creates the new NodePort first, which reduces or avoids downtime.
+
+- Single-node Couchbase cluster: When the node's NodePort changes, XDCR cannot reconnect automatically.
+In this case, you must manually update the replication configuration at couchbaseclusters.spec.xdcr.remoteClusters.hostname with the new IP:NodePort of the Couchbase node.
+
+- Multi-node Couchbase cluster: When a node's NodePort changes, XDCR reconnects to another node that still exposes a valid NodePort.
+However, if XDCR tries to reconnect through the updated node, you may still need to update couchbaseclusters.spec.xdcr.remoteClusters.hostname with the new port.
 
 [IMPORTANT]
 ====
@@ -287,7 +301,7 @@ spec:
 ----
 
 <.> The resource is labeled with `replication:from-my-cluster-to-remote-cluster` to avoid any ambiguity because by default the Operator will select all `CouchbaseReplication` resources in the namespace and apply them to all remote clusters.
-Thus the label is specific to the source cluster and target cluster.
+The label is specific to the source cluster and target cluster.
 
 We define a remote cluster on our local resource:
 
@@ -318,14 +332,14 @@ spec:
 <.> The correct hostname to use.
 The hostname is calculated as per the xref:howto-client-sdks.adoc#ip-based-addressing[SDK configuration how-to].
 
-<.> As we are not using client certificate authentication we specify a secret containing a username and password on the remote system.
+<.> As we're not using client certificate authentication, specify a secret containing a username and password on the remote system.
 
-<.> Finally we select replications that match the labels we specify, in this instance the ones that go from this cluster to the remote one.
+<.> Finally, select replications that match the labels specified, in this instance the ones that go from this cluster to the remote cluster.
 
 == Scopes and collections support
 
 With Couchbase Server version 7 and greater, scope and collections support is now present for XDCR.
-The Couchbase Kubernetes Operator fully supports the various options available to the Couchbase Server version it is running with, full details can be found in the xref:server:manage:manage-xdcr/replicate-using-scopes-and-collections.html[official documentation].
+The Couchbase Kubernetes Operator fully supports the various options available to the Couchbase Server version it's running with, full details can be found in the xref:server:manage:manage-xdcr/replicate-using-scopes-and-collections.html[official documentation].
 
 [NOTE]
 ====
@@ -396,7 +410,7 @@ Eventual consistency rules apply so if the bucket is still being created then we
 
 <.> This is an example of replicating only a specific collection `collection1` in scope `scope1`.
 
-<.> The target keyspace must be of identical size so as we are replicating from a collection we must also specify a target collection.
+<.> The target keyspace must be of identical size; as replicating from a collection requires also specifying a target collection.
 
 <.> Deny rules can be used to prevent replication of specific keyspaces.
 This is useful if for example you have a scope with a large number of collections and you want to replicate all but a small number.

modules/ROOT/pages/prerequisite-and-setup.adoc

@@ -146,6 +146,7 @@ This release supports the following managed Kubernetes services and utilities:
 == Persistent Volume Compatibility
 
 Persistent volumes are mandatory for production deployments.
+The Couchbase Operator is designed to work with any CSI-compliant storage driver and compatibility with different CSI implementations can be validated using the xref:concept-platform-certification.adoc[Operator Self-Certification Lifecycle] tooling.
 Review the Kubernetes Operator xref:best-practices.adoc#persistent-volumes-best-practices[best practices] for more information about cluster supportability requirements.
 
 == Hardware Requirements
@@ -176,6 +177,9 @@ The architecture of each node must be uniform across the cluster as the use of m
 NOTE: The official Couchbase docker repository contains multi-arch images which do not require explicit references to architecture tags when being pulled and deployed.
 However, when pulling from a private repository, or performing intermediate processing on a machine with a different architecture than the deployed cluster, the use of explicit tags may be required to ensure the correct images are deployed.
 
+IMPORTANT: For optimal performance with Couchbase Server 8.0 and later versions, in particular for vector search (FTS and GSI) workloads, use nodes that support AVX2 CPU instructions (x86-64-v3 Microarchitecture).
+For guidance on detecting AVX2 support and scheduling pods on AVX2-capable nodes, see xref:tutorial-avx2-scheduling.adoc[AVX2-Aware Scheduling for Couchbase Server].
+
 == RBAC and Networking Requirements
 
 Preparing the Kubernetes cluster to run the Operator may require setting up proper RBAC and network settings in your Kubernetes cluster.