Terminology

A single Couchbase Server instance running on a physical server, virtual machine, or a container. All nodes are identical: they consist of the same components and services and provide the same interfaces.

A cluster is a collection of nodes that are accessed and managed as a single group. Each node is an equal partner in orchestrating the cluster to provide facilities such as operational information (monitoring) or managing cluster membership of nodes and health of nodes.

A bucket is a logical container for a related set of items such as key-value pairs or documents. Buckets are similar to databases in relational databases. They provide a resource management facility for the group of data that they contain. Applications can use one or more buckets to store their data. Through configuration, buckets provide segregation along the following boundaries:

Item is the basic unit of data in a Couchbase Server. An item is a key-value pair where each stored value is identified by a unique key within the bucket.

vBuckets are physical partitions of the bucket data. By default, Couchbase Server creates a number of master vBuckets per bucket (typically 1024) to store the bucket data. Buckets may store redundant copies of data called replicas. Each replica also creates another set of vBuckets to mirror the active vBucket. The vBuckets that maintain replica data are called replica vBuckets. Every bucket has its own set of active and replica vBuckets and those vBuckets are evenly distributed across all nodes within the data service.

The cluster map contains a mapping of which services belong to which nodes at a given point in time. This map exists on all Couchbase nodes as well as within every instantiation of the client SDK. Through this map, the application is able to transparently identify the cluster topology and respond when that topology changes. Cluster map contains a vBucket map.

A vBucket map contains a mapping of vBuckets to nodes at a given point in time. This map exists on all Couchbase nodes as well as within every instantiation of the client SDK. Through this map, the application is able to transparently identify the nodes that contain the vBuckets for a given key and respond when the topology changes.

Replication is the process of creating additional copies of active data on alternate nodes. Replication is at the heart of the Couchbase Server architecture enabling high availability, disaster recovery, and data exchange with other big data products. It is the core enabler for

The topology of a cluster can change as nodes are added or removed due to capacity requirements or node failures. As the number of nodes changes, the rebalance operation is used to redistribute the load and adapt to the new topology of nodes. At its core, a rebalance operation for the data service is the incremental movement of vBuckets from one node to another. By moving vBuckets onto or off of nodes, these nodes become responsible for more or less data and begin handling more or less traffic from the applications. A rebalance operation also brings in or takes out nodes from the various services. While the rebalance operation is in progress, it also updates the cluster map on all clients with any topology changes. The Cluster Manager coordinates the movement and hand off of vBuckets and services during the rebalance operation. Rebalance is performed completely online and with minimal impact to the incoming workload.

Failover is the process that diverts traffic away from failing nodes to the remaining healthy nodes. Failover can be done automatically by the Couchbase cluster based on the health status of a node, or can be done manually by the administrator or an external script. A node that is failed over does not accept any new traffic.

As the cluster topology changes, nodes in the cluster go through a set of state transitions. Operations such as Add Node, Remove Node, Rebalance, and Failover cause state transitions. The following diagram lists the states and state transitions of the nodes in the cluster.

Figure 1. Node lifecycle