Concepts

Overview

Couchbase Community Edition is a high-performance, distributed NoSQL document database designed for scalable, flexible, and low-latency workloads. Running Couchbase on Kubernetes via Portworx Data Services (PDS) allows users to easily deploy, manage, and scale Couchbase clusters with built-in automation, persistent storage, high availability, and resilience.

With PDS, Couchbase Community Edition is deployed natively on Kubernetes using a custom operator that manages the full lifecycle of Couchbase clusters. PDS enables you to take advantage of Kubernetes-native constructs for dynamic scaling, fault tolerance, monitoring, and resource optimization.

PDS supports the Couchbase and tracks upstream releases to ensure compatibility and timely availability of new versions. Supported versions are listed here.

Clustering

Couchbase clusters in PDS consist of multiple nodes distributed across Kubernetes worker nodes to ensure fault tolerance and scalability. Each node contributes to the cluster’s compute, storage, and availability. Couchbase supports multiple node types (services), including:

• Data Service (KV): Stores and manages data.

• Index Service: Builds and maintains secondary indexes.

• Query Service: Parses and executes N1QL queries.

• Search, Analytics, and Eventing: (Limited in CE)

PDS uses Kubernetes StatefulSets to deploy Couchbase nodes. Each pod represents a Couchbase node, and the PDS Deployments Operator bootstraps the cluster, configures services, and handles node joining and failover.

Cluster membership and rebalance are handled automatically by Couchbase and monitored by the PDS operator.

Replication

Application-Level Replication

Couchbase Community Edition provides intra-cluster replication through data sharding and cross-node replication within the cluster to distribute document data across multiple nodes for redundancy.

• vBuckets are logical partitions of data automatically distributed across nodes.

• Each vBucket has a primary and optionally one or more replicas.

• When a node fails, its vBuckets can be promoted from replicas, ensuring availability.

Community Edition supports only local (intra-cluster) replication.

Storage-Level Replication

To enhance reliability, PDS uses Portworx Enterprise to provide persistent volumes with configurable replication across worker nodes or availability zones. This ensures that Couchbase node storage is resilient to underlying infrastructure failures.

By combining vBucket replication with storage-level replication, PDS delivers a robust and highly available deployment, even with the limitations of Couchbase CE.

Configuration

Couchbase server configurations in PDS are customizable through environment variables in application configuration templates. These settings allow fine-tuning of:

• RAM quotas per service

• Number of replicas

• Indexing and query options

• Logging levels

• Auto-failover parameters

PDS simplifies the process of customizing and managing these configurations at scale. For a full list of configurable parameters, refer to the PDS Couchbase Configuration Reference.

Scaling

PDS supports vertical and horizontal scaling for Couchbase deployments.

Vertical Scaling

Vertical scaling involves increasing or decreasing CPU and memory resources for Couchbase pods. These changes are applied with minimal disruption through rolling updates managed by the PDS operator.

Horizontal Scaling

Horizontal scaling adds or removes Couchbase nodes. PDS updates the StatefulSet replica count, and new pods automatically join the cluster. After nodes are added, a rebalance is triggered to redistribute data and workloads.

note

PDS assists with automation of initial join and basic cluster operations but does not override Couchbase’s rebalance requirements.

Connectivity

PDS provisions internal and external connectivity to Couchbase clusters via Kubernetes services of type LoadBalancer or ClusterIP, depending on user selection.

Endpoints

Each Couchbase pod receives a stable service endpoint, and the cluster is accessible via:

Service Name	Details
cb-<name>-<namespace>-<pod-id>-vip	Endpoint to a specific Couchbase pod
cb-<name>-<namespace>	Load-balanced access to Couchbase services

Backups and Restore

Backup and restore in PDS for Couchbase Community Edition leverages custom scripts and persistent storage snapshots. Since Couchbase CE lacks integrated backup tooling (like cbbackupmgr in EE), backups in PDS use:

• Persistent volume snapshots via Portworx

• Scheduled or ad hoc backup jobs

• Out-of-place restores to prevent data overwrites

Backups

• A snapshot of the persistent volume is created for each node.
• Snapshots are copied to remote object storage using Portworx cloud snapshotting for offsite backup (3-2-1 strategy).
• Backups are consistent at the volume level, covering all node data.

Restore

• Restore creates a new Couchbase cluster and reattaches restored volumes.
• Being a volume-level restore, it restores all documents along with bucket configurations and vBucket states.
• Selective (bucket-level or document-level) restore is not supported in CE.

Monitoring

Each Couchbase node in PDS includes a Prometheus exporter that exposes metrics on:

• Bucket and vBucket stats

• Memory and disk usage

• Request throughput

• Indexing metrics

• Node health

These metrics are available from the PDS Control Plane and can be visualized using Grafana or other Prometheus-compatible tools.

For the complete list of supported metrics and example usage, refer to the PDS Couchbase Metrics Reference.