See on GitHub

    Cluster Topology

    Changing the Topology

    Fetching the Topology

    Any client with Valid User privileges can fetch the topology from the server by sending the following REST API call:

    Action Method URL
    Fetch Topology GET /cluster/topology

    Modifying the Topology

    With Cluster Admin privileges, the client can modify the cluster through the Studio,
    or by using the following REST API calls:

    Action Method URL
    Add Node PUT /admin/cluster/node?url=node-url
    Remove Node DELETE /admin/cluster/node?url=node-tag

    Optional parameters (for the Add Node endpoint):

    Name Value Type Description
    tag string 1-4 uppercase unicode letters (default: 'A' - 'Z' assigned by order of addition)
    watcher bool Add the node as a Watcher (default: false)
    maxUtilizedCores uint Maximum number of cores that can be assigned to this node (default: number of processors)

    See the Cluster API page for usage examples.

    Nodes States and Types

    In Rachis every cluster node has a state and a type.

    Type

    The type defines the node's ability to vote on accepting a new raft command in the cluster,
    and elect a new leader when needed.

    Node Type Description
    Member A fully functional voting node in the cluster.
    Promotable A non-voting node.
    This is an intermediate stage until node is promoted by the Leader to a Member.
    Watcher A non-voting node that is still fully managed by the cluster.
    Can be assigned with databases and tasks. See more below.

    State

    The Rachis state defines the current role of the node in the cluster.

    Rachis State Description
    Passive Not a part of any cluster.

    Every newly created RavenDB server starts at the initial Passive state.
    A passive node can become a Leader of a single-node-cluster,
    or it can be added to an already existing cluster.

    A node that is removed from the topology moves back to the Passive state.
    Candidate Has no Leader and tries to get elected for leadership.
    Follower Has a Leader and operates normally.
    Leader-Elect Just elected for leadership, but will take office and become the leader only after the dummy noop raft command was successfully applied in the cluster.
    Leader Leader of the cluster. See more below.

    Figure 3. States Transitions

    Cluster Nodes States Flow

    1. New server/node will start as Passive, meaning it is not part of any cluster yet.
    2. When a node is added to a cluster, it immediately becomes the Leader if it is the only node in the cluster.
    3. When a node is added to a cluster and a Leader already exists, it will become Promotable (on its way to either becoming a Member or a Watcher - depending on what was specified when created.)
    4. Node will become a Member of the cluster if not specified otherwise.
    5. Node will become a Watcher if specified when adding the node.
    6. Member can be Demoted to a Watcher.
    7. Watcher can be Promoted to a Member. It will first become Promotable and a Member thereafter.
    8. Member (a regular Member or a Leader - but not a Watcher) can become a Candidate when a voting process for a new Leader takes place.
    9. When voting is over and a new Leader is elected, one candidate becomes the Leader and the rest go back to being his Followers.

    Leader

    • The Leader makes sure that decisions are consistent at the cluster level, as long as a majority of the nodes are functioning and can talk to the Leader.

    • For example, the decision to add a database to a node will be either accepted by the entire cluster (eventually) or fail to register altogether.

    • Raft Commands can't be accepted while there is no Leader or if the Leader is down.

    Watcher

    Increase your RavenDB cluster by adding Watchers with the advantage of not suffering from large voting majorities and the latencies they can incur, as watchers don't take part in majority calculations.

    • A Watcher can be assigned databases and tasks as a regular Member but is not included in the decisions making flow, so cluster decisions can be made with a small majority of nodes while the actual size of the cluster can be much higher.

    • Any number of Watchers can be added to handle the workload.

    Changing Node Type

    Node types can be altered on the fly by using the following REST API calls:

    Action Method URL Clearance
    Promote Watcher to be a Member POST /admin/cluster/promote ClusterAdmin
    Demote Member to be a Watcher POST /admin/cluster/demote ClusterAdmin
    Force Elections POST /admin/cluster/reelect Operator

    See the Cluster API page for usage examples.

    Home / Docs / Server / Clustering / Rachis / Cluster Topology