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:

      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

      Single Node

      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.

      Multi-Node

      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.

      Custom

      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.

      Manage Your Data

      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.

      Query Data with SQL++

      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.

      Primary and Secondary Index Reference

      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.

      Run a Function on Data Change

      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.

      Analyze Large Datasets

      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

      Single Node

      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.

      Multi-Node

      Choose between:

      • 3 nodes with 1 Service Group for the Data Service, Query Service, and Index Service

      • 5 nodes with 2 Service Groups:

        • Service Group 1: Data Service with 3 nodes

        • Service Group 2: Query and Index Service with 2 nodes

      • 7 nodes with the choice between 2 Service Group Configurations

        • Option 1

          • Service Group 1: Data Service with 3 nodes

          • Service Group 2: Query Service with 2 nodes

          • Service Group 3: Index Service with 2 nodes

        • Option 2

          • Service Group 1: Data Service with 3 nodes

          • Service Group 2: Query and Index Service with 2 nodes

          • Service Group 3: Search Service with 2 nodes

      Custom

      Defaults to 4 Service Groups:

      • Service Group 1: Data Service with 3 nodes

      • Service Group 2: Query Service with 2 nodes

      • Service Group 3: Index Service with 2 nodes

      • Service Group 4: Search Service with 2 nodes

      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

      Single Node

      Choose between:

      • 4vCPU 16 GB RAM (default)

      • 2vCPU 8 GB RAM

      Multi-Node

      Choose between:

      • 4vCPU 16 GB RAM

      • 8vCPU 16 GB RAM

      • 4vCPU 32 GB RAM

      • 8vCPU 32 GB RAM

      • 8vCPU 64 GB RAM

      • 16vCPU 64 GB RAM

      Custom

      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?

      Single Node

      Storage can only be expanded up to 100 GB with the Default Compute Configuration

      Multi-Node

      Total storage is based on disk type and your chosen cloud provider:

      AWS

      Choose between GP3 or IO2. GP3 disks are general-purpose and provide the best balance of price and performance, for provisioning performance and storage capacity independently. IO2 disks have higher performance, more durability, and better reliability.

      GCP

      PD-SSD only - best for higher performance with lower latency and more IOPS.

      Azure

      Choose between Premium SSD or Ultra disks. Premium SSDs are best for higher performance with lower latency and more IOPS. Ultra Disks are best for intensive, transaction-heavy workloads with low latency and consistent IOPS.

      AWS

      Your IOPS range depends on your disk type.

      GCP

      Your IOPS value is chosen based on your storage size, with 30 read and write IOPS per GB of storage.

      Azure

      Your IOPS value is chosen or limited based on your chosen storage size.

      Custom

      Total storage is based on disk type and your chosen cloud provider:

      AWS

      Choose between GP3 or IO2. GP3 disks are general-purpose and provide the best balance of price and performance, for provisioning performance and storage capacity independently. IO2 disks have higher performance, more durability, and better reliability.

      GCP

      PD-SSD only - best for higher performance with lower latency and more IOPS.

      Azure

      Choose between Premium SSD or Ultra disks. Premium SSDs are best for higher performance with lower latency and more IOPS. Ultra Disks are best for intensive, transaction-heavy workloads with low latency and consistent IOPS.

      AWS

      Your IOPS range depends on your disk type.

      GCP

      Your IOPS value is chosen based on your storage size, with 30 read and write IOPS per GB of storage.

      Azure

      Your IOPS value is chosen or limited based on your chosen storage size.

      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

      Single Node

      Basic

      Developer Pro (default)

      Multi-Node

      Basic

      Developer Pro (default)

      Enterprise

      Custom

      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

      Single Node

      1 Availability Zone

      Multi-Node

      Multiple Availability Zones, based on region.

      Custom

      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

      See Also

      See the following pages for more information about managing clusters: