Cluster: Cluster API

The easiest way to manage a RavenDB cluster is through the Management Studio's Cluster View.
All cluster operations are available through the GUI. However, sometimes you'd want to automate things.

In this section we will demonstrate of how to perform certain cluster operations programmatically using the REST API. In the first example we will show how to make a secure call using PowerShell, cURL and the RavenDB C# Client. The rest of the examples are cURL only.

If authentication is turned on, a client certificate with either Cluster Admin or Operator Security Clearance must be supplied, depending on the endpoint.

Add node to the cluster

Adding a node to the cluster can be done using 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 we 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 (smallest)

SecurityClearance: Cluster Admin

C# Client

  • To make a secure call, the Document Store must be supplied with the client certificate (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>&assignedCores=<assigned-cores>"));

Powershell

[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 $cert"

cURL

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

Delete node from the cluster

Deleting a node from the cluster can be done using 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 -

SecurityClearance: Cluster Admin

Example

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

Promote a Node

Promoting a node can be done using 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 -

The POST request body should be empty.

SecurityClearance: ClusterAdmin

Example

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

Demote a Node

Demoting a node can be done using 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 -

The POST request body should be empty.

SecurityClearance: ClusterAdmin

Example

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

Force Elections

Forcing an election can be done using an empty HTTP POST request to the /admin/cluster/reelect endpoint:

SecurityClearance: Operator

Example

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

Force Timeout

Forcing a timeout can be done using an empty HTTP POST request to the /admin/cluster/timeout endpoint:

SecurityClearance: Operator

Example

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

Bootstrap Cluster

Bootstrapping the cluster can be done using an empty HTTP POST request to the /admin/cluster/bootstrap endpoint: Note: This option is only available when the server is in the Passive state.

SecurityClearance: Cluster Admin

Example

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