Cluster: Cluster API

• You can manage a RavenDB cluster using Studio's Cluster View.
  All cluster operations can be performed through Studio. However, you may sometimes prefer to automate these operations.

• In this article, we demonstrate several cluster operations you can perform using the REST API.
  The first example shows how to make a secure call using PowerShell, cURL, and the RavenDB C# client.
  All other examples are cURL only.

• If authentication is enabled, each call must present a client certificate with the security clearance required by its endpoint: Cluster Admin for most operations, and Operator for Force elections and Force timeout.

• In this article:

  • REST API endpoints
    • Add node to the cluster
    • Delete node from the cluster
    • Promote a node
    • Demote a node
    • Bootstrap cluster
    • Force elections
    • Force timeout

REST API endpoints

Each operation below is performed by calling a REST endpoint.

Add node to the cluster

You can add a node to the cluster by sending an HTTP PUT request to the /admin/cluster/node endpoint with the following arguments:

Argument	Description	Required	Default
new-node-url	The address of the new node you want to add to the cluster	true	-
new-node-tag	1-4 uppercase unicode letters	false	A - Z assigned by order of addition
is-watcher	Add the new node as a watcher	false	false
max-utilized-cores	The maximum number of cores that can be assigned to the new node	false	Number of processors on the machine or the license limit, the smaller of the two

Required security clearance: Cluster Admin

Example: Add a node

• C#
• PowerShell
• cURL

To make a secure call, the Document Store must be provided with the client certificate (see example).

store.GetRequestExecutor().HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Put, "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<new-node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>"));

To make a secure call, load the client certificate from a PFX file and pass it to the request.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$clientCert = Get-PfxCertificate -FilePath <path-to-pfx-cert>
Invoke-WebRequest -Method Put -URI "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<new-node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>" -Certificate $clientCert

To make a secure call, provide the client certificate and private key using the --cert and --key options.

curl --cert <path-to-cert> --key <path-to-key> -X PUT "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>"

Delete node from the cluster

You can delete a node from the cluster by sending an HTTP DELETE request to the /admin/cluster/node endpoint with the following argument:

Argument	Description	Required	Default
node-tag	The tag of the node to delete	true	-

Required security clearance: Cluster Admin

Check the replication factor before removing a node

Removing a node removes from the cluster the database copies this node held:

• A database whose only copy was on the removed node will become inaccessible.
• A multi-node database that had one of its copies on the removed node will have its replication factor reduced by one.

Prior to removing a node, make sure that all the databases it holds have copies on other nodes.

Example: Delete a node

curl -X DELETE "https://<server-url>/admin/cluster/node?nodeTag=<node-tag>"

Promote a node

Promoting a node turns a watcher into a voting member that participates in the cluster quorum.
You can promote a node by sending an HTTP POST request to the /admin/cluster/promote endpoint with the following argument:

Argument	Description	Required	Default
node-tag	The tag of the node to promote	true	-

• No request body is required.
• Required security clearance: Cluster Admin

Example: Promote a node

curl -X POST "https://<server-url>/admin/cluster/promote?nodeTag=<node-tag>" -d ''

Demote a node

Demoting a node turns a voting member into a watcher that no longer participates in the cluster quorum.
You can demote a node by sending an HTTP POST request to the /admin/cluster/demote endpoint with the following argument:

Argument	Description	Required	Default
node-tag	The tag of the node to demote	true	-

• No request body is required.
• Required security clearance: Cluster Admin

Example: Demote a node

curl -X POST "https://<server-url>/admin/cluster/demote?nodeTag=<node-tag>" -d ''

Bootstrap cluster

You can bootstrap the cluster by sending an empty HTTP POST request to the /admin/cluster/bootstrap endpoint.
Note that bootstrapping takes effect only while the server is in the Passive state. On a server that has already formed or joined a cluster, the request has no effect.

Required security clearance: Cluster Admin

Example: Bootstrap the cluster

curl -X POST "https://<server-url>/admin/cluster/bootstrap" -d ''

Force elections

You can force an election by sending an empty HTTP POST request to the /admin/cluster/reelect endpoint.

Required security clearance: Operator

Example: Force an election

curl -X POST "https://<server-url>/admin/cluster/reelect" -d ''

Force timeout

You can force a timeout by sending an empty HTTP POST request to the /admin/cluster/timeout endpoint.

Required security clearance: Operator

Example: Force a timeout

curl -X POST "https://<server-url>/admin/cluster/timeout" -d ''