--- title: Metadata Management pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-server/edit/release/8.0/modules/learn/pages/clusters-and-availability/metadata-management.adoc xref: xref:server:learn:clusters-and-availability/metadata-management.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/current/learn/clusters-and-availability/metadata-management.html) # Metadata Management > A Couchbase Cluster's _metadata_ describes its configuration. Some categories of metadata are maintained by means of a _consensus protocol_; others by means of _gossip replication_. ## [](#understanding-couchbase-server-metadata-management)Understanding Couchbase-Server Metadata-Management In Couchbase Server version 7.0 and later, metadata is managed by means of _Chronicle_; which is a _consensus-based_ system, based on the [Raft](https://raft.github.io/) algorithm. Chronicle manages: * The _node-list_ for the cluster. * The _status_ of each node. * The _service-map_ for the cluster, which indicates on which nodes particular services have been installed. * _Bucket definitions_, including the placement of scopes and collections. * The _vBucket maps_ for the cluster. The process whereby this metadata is maintained is described below, in [Consensus-Based Metadata-Management](#consensus-based-metadata-management). Additional cluster-metadata is handled by Couchbase Server's _legacy_ metadata-management system, which is based on _gossip-replication_. This legacy-managed metadata includes: * Compaction settings. * Security settings. * XDCR replications. * Settings and metadata for all services. * Per-node configuration settings. Changes to the legacy-managed metadata are asynchronously replicated across the nodes with _eventual consistency_, by means of _gossip replication_. This means that when a metadata change occurs on any node, that node attempts to replicate the change to all other nodes. Additionally, each node periodically pulls the configuration of some other, randomly selected node; in order to update its own configuration in cases where it has somehow missed an earlier change-notification. By these means, configuration generally spreads rapidly and reliably through the cluster. When a cluster-wide activity such as rebalance or failover needs to occur, this is performed by the cluster's _orchestrator_ (its master node). To do so, the orchestrator obtains a _lease_ on metadata changes; to ensure that no topology-related metadata changes can be made by any other node, while the cluster-wide activity is in process. ## [](#consensus-based-metadata-management)Consensus-Based Metadata-Management Starting with version 7.0, Couchbase Server provides consensus-based metadata management, by means of _Chronicle_; which is a methodology based on the [Raft](https://raft.github.io/) algorithm. Chronicle is: * Strongly consistent. * Supportive of full linearizability. * Fully tested with [Jepsen](https://jepsen.io/). Couchbase-Server administrators are not required to be familiar with the internal workings of Chronicle. However, for informational purposes, a sketch of how Chronicle works is provided below. See the [Raft](https://raft.github.io/) specification for a complete account of the algorithm on which Chronicle is based. ### [](#logs-leaders-and-followers)Logs, Leaders, and Followers Each node maintains a log, into which metadata change-commands are saved. Across the cluster, logs are maintained with consistency. At intervals, to control log-size and ensure availability, on each node, compaction is performed, and snapshots are taken. Each node is considered to be in the role of either _leader_ or _follower_; with at most one node the leader at any time. Only the leader can transmit metadata change-commands. The role of leader may periodically be exchanged between nodes, by the process described below. ### [](#leadership-election)Leadership and Election The leader is responsible for communicating with clients: this includes providing the current topology of the cluster, and receiving requests for topology change. The leader distributes clients' requests to the followers, as change-commands, which are to be appended to the log-instance on each node. In the event of the leader becoming non-communicative (say, due to network failure), a follower can advertise itself as a _candidate_ for leadership. Followers, receiving the communication, respond with _votes_. Every vote received by the candidate, including its own, constitutes one node's support for the candidacy. If a majority of nodes are supportive, a new _term_ is started, with the elected node as leader. Nodes are given the right to vote only when fully integrated into the cluster. Nodes not fully integrated (as is the case, for example, during the process of their addition) are considered _replicas_. Replicas participate in the exchange and commitment of information (see immediately below), but do not vote. Once a node's addition is complete, the node is able to vote. ### [](#data-exchange-and-commitment)Data Exchange and Commitment When the leader transmits a change-command to followers, each follower appends the command to its own instance of the log. Once a majority of nodes confirm that they have done so, the leader performs a _commit_; and informs the other nodes. Once informed, the other nodes also commit. _Committing_ means updating the _Replicated State Machine_, according to the command. This is described below. Following commitment, the leader returns the execution-result to the client. ### [](#network-failures-and-consequent-inconsistencies)Network Failures and Consequent Inconsistencies When network failures prevent change-commands from reaching a majority of nodes, the information is appended to the logs of those nodes that have received it; but is not committed. Whenever a leader commits a new log entry, it also commits all preceding uncommitted entries in its log; and each commitment is applied, across the cluster, to all instances of the _Replicated State Machine_. ### [](#replicated-state-machine)Replicated State Machine The _Replicated State Machine_ is a key-value store, resident on each node, that contains the cluster's topographical data. Clients that require such data receive it from the leader's key-value store. The key-value pairs in the store are generated and updated based on change-commands appended to the replicated log. A change-command may: * Add a key-value pair. * Update the value of a key-value pair. * Update the value of a key-value pair, based on logical constraints. * Update the values of key-value pairs transactionally. Each key-value pair has a revision number that corresponds to the sequence of change-commands applied to the store. ### [](#quorum-failure)Quorum Failure A _quorum failure_ occurs when half or more of the nodes in the cluster cannot be contacted. In this situation, commitment is prohibited; until either the communication problem is remedied, or the non-communicative nodes are failed over unsafely. In consequence, prior to remedy or failover, for the duration of the quorum failure: * Buckets, scopes, and collections can neither be created nor dropped. * Nodes cannot be added, joined, failed over safely, or removed. See [Performing an Unsafe Failover](hard-failover.md#performing-an-unsafe-failover), for information on failing over nodes in response to a quorum failure.