Configure Your Cluster
- Capella Operational
Understand the different configuration options available to customize your Couchbase Capella cluster.
A Capella cluster is a managed deployment of Couchbase Server. Clusters are 1 or more instances of Couchbase Server, which run on independent nodes inside Couchbase’s Virtual Private Cloud (VPC) and your chosen cloud provider region.
Clusters exist inside projects. You can create projects inside your organization to control user access to your specific clusters.
Cluster Configuration Options
When you Create A Paid Cluster, you can configure the following options:
After you create a cluster, if you want to Modify a Paid Cluster, you can only change:
-
Your cluster name and description
Basic Cluster Options
When you create a new paid cluster, you can choose a basic option to automatically choose some of your cluster’s settings:
| Cluster Option | Description |
|---|---|
Deploy a cluster on a single node configuration. Single Node clusters are best for prototyping or learning. You can only use a single Service Group and a single Availability Zone. |
|
Deploy a cluster on a Multi-Node configuration by choosing from one of the available pre-configured templates for a 3 node, 5 node, or 7 node cluster. Using the Multi-Node option helps you quickly configure multiple Service Groups and choose the best compute and storage configuration. Multi-Node clusters also support multiple Availability Zones. |
|
Deploy a cluster with a custom configuration suited to your needs. Custom configurations are best for heavy, enterprise workloads. Create Service Groups and assign a specific number of nodes to each Group. You can also customize the compute and storage for the nodes in each Group. By default, Custom configurations start with 4 Service Groups with a total of 9 nodes. Custom clusters also support multiple Availability Zones. |
Cloud Service Provider, Region, and CIDR Block
Capella offers cluster deployments through the following Cloud Service Providers (CSPs):
Your chosen CSP for your cluster changes your available configuration options, such as the region where you deploy your cluster, compute options, and the disk type, storage size, and IOPS for your nodes.
For the available regions for each CSP, see:
Your chosen region can change your available Availability Zone options.
You can choose to customize the CIDR block for your Capella cluster or leave it as the default value. Use IPv4 syntax to define your CIDR block for your cluster.
| If you plan to use private networks (VPC or VNet Peering) with your Capella cluster, make sure to customize your CIDR block to avoid overlap between your VPC CIDR and Capella. |
Couchbase Server Version
For the best experience with your Couchbase Capella cluster, always create and deploy a new cluster with the latest version of Couchbase Server.
You can choose a previous version of Couchbase Server to maintain compatibility with existing applications.
Capella deploys new and upgraded clusters with the latest available patch version available for each minor Couchbase Server release. Capella schedules version upgrades for clusters when they become available.
For more information about how to upgrade or schedule maintenance for a cluster, see Upgrading a Cluster.
Couchbase Server Guardrails
For safe and reliable cluster operations, and to minimize the severity of cluster outages, Capella clusters using Couchbase Server 7.6 or later have guardrails in place. These guardrails proactively monitor for specific system thresholds. When a cluster meets these thresholds, these guardrails automatically prevent the following cluster operations, which during these conditions can put the cluster at severe risk of outage and downtime:
-
Bucket writes
-
Bucket creation
-
Collection creation
-
Topology changes that involve rebalancing
Server-level enforcement thresholds are designed to ensure the optimal and reliable usage of available system resources by various workloads. These thresholds are as follows:
| Cluster Metric | Threshold |
|---|---|
Data Service Resident Ratio (Couchstore) |
<= 1% |
Data Service Resident Ratio (Magma) |
<= 0.1% |
Free Disk Space |
<= 4% |
# of Buckets |
<= 0.2 cores per bucket |
Services and Service Groups
Use Services to use and maintain your data on your Capella cluster.
Deploy Services through Service Groups, which can contain 1 or more nodes:
-
If you chose the Single Node option, you can create a single Service Group on a single node.
-
If you chose the Multi-Node option you can choose a pre-configured set of Services and nodes to add to your cluster. You can choose to add or remove specific Services from your configuration.
-
If you chose the Custom option, you can create multiple Service Groups and assign a specific number and node configuration for each Service Group, up to a maximum of 27 nodes across all Service Groups.
For more information about the default node and Service Group configurations, see Node Configuration.
You can deploy, maintain, and provision Services independently with Multi-Dimensional Scaling and customize your nodes to suit each Service.
The following Services can be deployed on a Capella cluster:
| Service | Description | Further Information |
|---|---|---|
Data Service |
Use the Couchbase Data Service to store, set, and retrieve data items with a key on your Capella cluster. Every cluster must have at least 1 node running the Data Service. It’s recommended to run the Data Service on at least 3 nodes in a production environment. Make sure to deploy the Data Service on a virtual machine that has a large amount of memory. |
|
Query Service |
Use the Query Service to run queries on your data with the SQL++ query language and get results. To use the Query Service, you must deploy the Data Service and the Index Service. The Query Service requires a minimum of 2 nodes for best results in a production environment. |
|
Index Service |
Use the Index Service to create primary and secondary indexes on your data and get better query performance with the Query Service. The Index Service requires a minimum of 2 nodes for best results in a production environment. |
|
Search Service |
Use the Search Service to create Search indexes and add near real-time search capabilities to your applications. Search indexes support search for structured or unstructured text, vectors, dates, numbers, CIDR notations, and geospatial data. The Search Service requires a minimum of 2 nodes for best results in a production environment. You cannot deploy the Search Service on a Single Node cluster using the 2vCPU 8 GB RAM compute configuration. To use the Search Service on a Single Node cluster, you must use the 4vCPU 16 GB RAM configuration. |
|
Eventing Service |
Use the Eventing Service to create custom JavaScript snippets that run in response to document mutations or as scheduled by timers. These custom code snippets can support near real-time handling of data changes. The Eventing Service requires a minimum of 2 nodes for best results in a production environment. You cannot deploy the Eventing Service on a Single Node cluster using the 2vCPU 8 GB RAM compute configuration. To use the Eventing Service on a Single Node cluster, you must use the 4vCPU 16 GB RAM configuration. |
|
Analytics Service |
Use the Analytics Service to analyze large datasets with complex analytical queries. The Analytics Service supports large join, set, aggregation, and grouping operations, which can be long-running use a lot of memory and CPU resources. You can create shadow copies of the data you want to analyze and link from external data sources. The Analytics Service uses the SQL++ for Analytics query language. For more information about SQL++ for Analytics, see the SQL++ for Analytics Reference. The Analytics Service requires a minimum of 2 nodes for best results in a production environment. You cannot deploy the Analytics Service on a Single Node cluster using the 2vCPU 8 GB RAM compute configuration. To use the Analytics Service on a Single Node cluster, you must use the 4vCPU 16 GB RAM configuration. |
| You can only add a Service once to a cluster. |
Node Configuration
Add and configure nodes in a Capella cluster to change the computing resources available to your Service Groups.
A single Service Group can contain 1 or more nodes. All nodes in a Service Group share the same Compute Configuration and Storage Configuration.
| Cluster Option | Available Node Configurations |
|---|---|
1 node with the Data Service, Index Service, and Query Service. If you choose the default compute configuration, you can add the Search, Analytics, or Eventing Services. |
|
Choose between:
|
|
Defaults to 4 Service Groups:
Can add up to a maximum of 27 total nodes across all Service Groups |
You can add and remove nodes from Services and Service Groups after you deploy your cluster. For more information, see Add or Remove Nodes.
Compute Configuration
For each Service Group in your Capella cluster, you must choose the compute configuration for your nodes.
Your compute configuration controls the CPU cores and total RAM for each node in that Service Group. RAM is measured in capacity (GB) and CPU is measured by the number of vCPUs.
Different Services might have different CPU and RAM needs. If a Service Group needs more computing resources, you can change your compute configuration any time after you deploy your cluster.
|
Node RAM Allocations
If you deploy multiple Services in a Service Group, Capella distributes the memory allocated to each node in that group between the operating system and all deployed Services. Capella gives 20% of the available RAM on a node to the operating system. It divides the remaining RAM evenly between Services in the Service Group. For example, if there was 25 GB of RAM available on a node in a Service Group that needed to run 3 Services, each Service would get 8.3 GB of RAM (25/3). If you plan to run more than 1 Service on the nodes in your Service Groups, make sure to size your nodes with appropriate compute resources. For production clusters, consider running each of your Services with their own dedicated nodes to give them enough RAM. |
Your available compute configuration options depend on your basic cluster option:
| Cluster Option | Available Compute Configuration |
|---|---|
Choose between:
|
|
Choose between:
|
|
Compute options are based on your chosen cloud provider: |
| If you choose a compute configuration that cannot support your Storage Configuration, Capella displays a warning. |
Storage Configuration
For each Service Group in your Capella cluster, you must choose the storage configuration for your nodes.
Your chosen cluster option and Cloud Service Provider (CSP) changes your available storage options. Different CSPs have different storage sizes, available disk types, supported IOPS values, and auto-scaling support.
Your Compute Configuration must be large enough to support your chosen storage configuration. Capella displays a warning if your compute cannot support your chosen storage configuration.
| Cluster Option | Storage Expandable? | Disk Type Configurable? | IOPS Configurable? |
|---|---|---|---|
Storage can only be expanded up to 100 GB with the Default Compute Configuration |
✖ |
✖ |
|
Total storage is based on disk type and your chosen cloud provider: |
✔
|
✔
|
|
Total storage is based on disk type and your chosen cloud provider: |
✔
|
✔
|
| Adjusting your IOPS value affects performance and cost for your cluster. For AWS GP3, AWS IO2, and Azure Ultra Disk, Capella uses the recommended defaults for your IOPS. You can go higher than the default IOPS value, but you cannot go lower. For more information about IOPS, see IOPS Defaults. |
Auto-Scaling Configuration
Auto-Scale configuration is based on your chosen cloud provider and cluster option.
Single Node Clusters
Auto-Scaling is always on for Single Node clusters.
| Even with Auto-Scale enabled, Couchbase Capella support will contact you to reduce your storage usage if your Single Node cluster exceeds your chosen storage configuration of 50 GB or 100 GB. Try not to exceed your chosen storage configuration when using a Single Node cluster. |
AWS clusters can only auto-expand storage once every 6 hours. For more information about AWS storage scaling limitations, see the AWS limitations documentation.
After you expand storage on any cluster, your storage size cannot automatically decrease. To decrease storage capacity, you must replace and rebalance nodes, which can result in data movement and a slower process, based on your data size and available computing resources.
Multi-Node and Custom Clusters
For Multi-Node or Custom clusters deployed on AWS or GCP, automatic storage scaling is always on. You cannot turn off Auto-Scaling.
AWS clusters can only auto-expand storage once every 6 hours. For more information about AWS storage scaling limitations, see the AWS limitations documentation.
For Multi-Node or Custom clusters deployed on Azure, Auto-Scaling is turned off by default, as it requires replacing and rebalancing nodes. This results in data movement and can affect performance until Auto-Scaling completes. You can choose whether to turn on Auto-Scale, or leave it turned off.
After you expand storage on any cluster, your storage size cannot automatically decrease. To decrease storage capacity, you must replace and rebalance nodes, which can result in data movement and a slower process, based on your data size and available computing resources.
For more information about cluster scaling, see Cluster Scaling or Storage Auto-Expansion.
Support Plan
Choose the Support Plan for your cluster to change the level of support you receive from Couchbase Capella Support for that cluster.
Your Support Plan affects the hourly billing price for your cluster and can affect your access to some Capella features.
For more information about the available Support Plans, see Support Overview.
| Cluster Option | Available Support Plans |
|---|---|
Basic Developer Pro (default) |
|
Basic Developer Pro (default) Enterprise |
|
Basic Developer Pro Enterprise (default) |
Availability Zones
Based on your chosen cluster option, CSP region, and Support Plan, you can choose between a Single or Multiple Availability Zones for your cluster.
Availability Zones can help minimize downtime and make sure your data remains highly available and fault resistant. It’s recommended to use Multiple Availability Zones for production clusters with the Multi-Node or Custom cluster option.
| Clusters on the Basic Support Plan support only a Single Availability Zone. |
| Cluster Option | Availability Zones |
|---|---|
1 Availability Zone |
|
Multiple Availability Zones, based on region. |
|
Multiple Availability Zones, based on region. |
AWS Availability Zones
If you deploy a cluster on AWS, you can choose the specific Availability Zone or Zones to use with your cluster.
Capella provides the physical zone location names for AWS Availability Zones, using AZ IDs. These IDs may be different from the labels you would see in your own AWS configurations. For more information about AZ IDs, see the AWS Elastic Compute Cloud documentation