Permissions required: cluster_observer.
None.
Returns the current state of the cluster, collecting items about the
cluster similar to riak admin cluster status.
On success, returns a JSON object of the form:
{
"current_cluster": [CLUSTER_MEMBER1, ...],
"down_nodes" : [DOWN_NODE1, ...],
"final_cluster" : [FINAL_MEMBER1, ...],
"staged_changes" : [STAGED_CHANGE1, ...],
"transfers" : [TRANSFER1, ...]
}
Example: for a cluster of two devrel nodes with no staged changes and all transfers completed, the response is as follows:
{
"result" : {
"current_cluster" : [
{
"claimant" : false,
"is_me" : true,
"low_mem" : false,
"mem_erlang" : 91029576,
"mem_total" : 16694644736,
"mem_used" : 7158771712,
"name" : "dev1@127.0.0.1",
"pending_pct" : 0.5,
"reachable" : true,
"replacement" : null,
"ring_pct" : 0.5,
"services" : [
"riak_repl",
"riak_pipe",
"riak_kv"
],
"staged_action" : null,
"status" : "valid",
"system_info" : {
"nodename" : "dev1@127.0.0.1",
"riak_version" : "3.4.0",
"system_version" : "Erlang/OTP 26 [erts-14.2.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:64] [jit:ns]",
"uptime" : 2954,
"uptime_str" : "49 minutes, 14 sec"
}
},
{
"claimant" : true,
"is_me" : false,
"low_mem" : false,
"mem_erlang" : 77394144,
"mem_total" : 16694644736,
"mem_used" : 7158771712,
"name" : "dev2@127.0.0.1",
"pending_pct" : 0.5,
"reachable" : true,
"replacement" : null,
"ring_pct" : 0.5,
"services" : [
"riak_repl",
"riak_pipe",
"riak_kv"
],
"staged_action" : null,
"status" : "valid",
"system_info" : {
"nodename" : "dev2@127.0.0.1",
"riak_version" : "3.4.0",
"system_version" : "Erlang/OTP 26 [erts-14.2.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:64] [jit:ns]",
"uptime" : 2959,
"uptime_str" : "49 minutes, 19 sec"
}
}
],
"down_nodes" : [],
"final_cluster" : [],
"staged_changes" : [],
"transfers" : []
}
}
With ongoing transfers, the "transfers" key will have elements as
follows:
"transfers" :
[
{
"count" : 32,
"node" : "dev2@127.0.0.1",
"state" : "stopped"
},
{
"count" : 32,
"node" : "dev1@127.0.0.1",
"state" : "waiting_to_handoff"
}
]
With leave/join operations planned, keys "final_cluster" and
"staged_changes" will contain the following elements:
"final_cluster" : [
{
"name" : "dev2@127.0.0.1",
"pending_pct" : 0,
"ring_pct" : 0
},
{
"name" : "dev1@127.0.0.1",
"pending_pct" : 100,
"ring_pct" : 100
},
"staged_changes" : [
{
"action" : "leave",
"name" : "dev2@127.0.0.1"
}
]
and the "staged_action" key in the affected node's CLUSTER_MEMBER entry under
"current_cluster" will change from null to the corresponding value
to indicate the action.
Permissions required: cluster_observer, cluster_admin.
{"include_transitions" : OPTION }
Get a plan of staged changes. Equivalent to riak admin cluster plan.
Parameter "include_transitions" is optional; if OPTION is "full"
(default), key transitions will include all items returned by
riak_core_claimant:plan/0. If it is "short", chring.node_entries
and members[].md fields from ring and new_ring will be omitted.
On success,
{"result":
{
"actions" : ACTIONS,
"transitions" : TRANSITIONS
}
}
Example (with "include_transitions" : "full"):
{
"result" : {
"actions" : [
{
"action" : "leave",
"node" : "dev2@127.0.0.1"
}
],
"transitions" : [
{
"new_ring" : {
"chring" : {
"node_entries" : [
{
"idx" : "0",
"node" : "dev1@127.0.0.1"
},
{
"idx" : "22835963083295358096932575511191922182123945984",
"node" : "dev1@127.0.0.1"
},
...
],
"num_partitions" : 64
},
"claimant" : "dev2@127.0.0.1",
"clustername" : {
"name" : "dev2@127.0.0.1",
"ts" : "2026-05-24T19:51:16+01:00"
},
"members" : [
{
"md" : {
"$riak_capabilities" : {
"riak_core:bucket_types" : "[true,false]",
...
},
"gossip_vsn" : 2,
"participate_in_coverage" : true
},
"member_status" : "valid",
"node" : "dev1@127.0.0.1",
"vclock" : [
{
"counter" : 28,
"node" : "dev1@127.0.0.1",
"ts" : 63946928738
},
...
]
},
...
],
"meta" : {
"$nodes_locations_changed" : {
"lastmod" : 63946867882,
"value" : false
}
},
"next" : [
{
"idx" : "45671926166590716193865151022383844364247891968",
"mods" : [],
"next_owner" : "dev1@127.0.0.1",
"owner" : "dev2@127.0.0.1",
"status" : "awaiting"
},
...
],
"nodename" : "dev2@127.0.0.1",
"rvsn" : [
{
"counter" : 7,
"node" : "dev2@127.0.0.1",
"ts" : 63946971039
}
],
"seen" : [
{
"nodename" : "dev1@127.0.0.1",
"vclock" : [
{
"counter" : 29,
"node" : "dev1@127.0.0.1",
"ts" : 63946928757
},
{
"counter" : 119,
"node" : "dev2@127.0.0.1",
"ts" : 63946928757
}
]
},
{
"nodename" : "dev2@127.0.0.1",
"vclock" : [
{
"counter" : 29,
"node" : "dev1@127.0.0.1",
"ts" : 63946928757
},
{
"counter" : 119,
"node" : "dev2@127.0.0.1",
"ts" : 63946928757
}
]
}
],
"vclock" : [
{
"counter" : 29,
"node" : "dev1@127.0.0.1",
"ts" : 63946928757
},
{
"counter" : 120,
"node" : "dev2@127.0.0.1",
"ts" : 63946971039
}
]
},
"ring" : {
...
}
On error,
{"error": ERROR_STRING}
Permissions required: cluster_observer, cluster_admin.
None.
Clear the plan of staged changes, if it exists. Equivalent to riak admin cluster clear.
Permissions required: cluster_observer, cluster_admin.
None.
Commits the plan. Equivalent to riak admin cluster commit.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to stage for joining the cluster.
Equivalent to riak admin cluster join NODE.
Stage a node to join the cluster.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to stage for leaving.
Equivalent to riak admin cluster leave NODE.
Stage a node to leave the cluster. If committed, the affected node will hand off all its data to other nodes in the cluster and shut down.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to stage for removing.
Equivalent to riak admin cluster remove NODE.
Stage a request for a node to be forcefully removed from the cluster. If committed, all partitions owned by the node will immediately be reassigned to other nodes. No data on the affected node will be transfered to other nodes, and all replicas on it will be lost.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE1, "with": NODE2}
NODE is the node to be replaced with REPLACEMENT.
Equivalent to riak admin cluster replace NODE1 NODE2.
Stage a node to be replaced with another in the cluster. When committed, node NODE1 will handoff all of its data to NODE2 and then shut down. The current implementation requires NODE2 to be a fresh node that is joining the cluster and does not yet own any partitions of its own.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE1, "with": NODE2}
NODE1 is the node to be force-replaced with NODE2.
Stage a request for NODE1 to be forcefully replaced by NODE2.
If committed, all partitions owned by NODE1 will immediately be
reassigned to NODE2. No data on NODE1 will be transfered,
and all replicas on NODE1 will be lost. As with ClusterStageReplace,
NODE2 must be a fresh node that is joining the cluster
and does not yet own any partitions of its own.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to mark as 'down'.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to stop.
Permissions required: cluster_admin.
{"node": NODE}
NODE is the node to collect application environment variables on.
On success,
{"result": APPENV}
APPENV is a proplist of all Erlang applications and their
environments, as a string produced by passing it through
io_lib:format("~120p\n", [AllAppEnvAsProplist]).
On error,
{"error": ERROR_STRING}
Permissions required: cluster_observer, cluster_admin.
{"node": NODE, "config": CONFIG}
NODE is the node to put application environment
variables on, and CONFIG is a string that can be parsed with
erl_scan:string/1 and erl_parse:parse_term/1, of the result of
printing a proplist of all application environments with
io_lib:format/2, or a fragment of such proplist. The final . is
not required.
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to pull advanced.config from.
On success,
{"result": CONFIG}
CONFIG is the contents of $PLATFORM_ETC_DIR/advanced.cofig, as a string produced by passing it through
io_lib:format("~120p\n", [Config]).
On error,
{"error": ERROR_STRING}
Permissions required: cluster_observer, cluster_admin.
{"node": NODE, "config": CONFIG}
NODE is the node to put application environment variables on, and
CONFIG is a string that can be parsed with erl_scan:string/1 and
erl_parse:parse_term/1, of the the entire contents of
advanced.config, without a final ..
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
NODE is the node to restart. {: .note }
This action requires
riak_deadmanshand. If it is not running, the request will succeed but the node will not be restarted.
Permissions required: cluster_observer.
{"nodes": NODES}
Report any ongoing repairs on NODES.
On success:
{
"result" : [
{
"node" : "dev1@127.0.0.1",
"status" : [
{
"idx" : "205523667749658222872393179600727299639115513856",
"mod" : "riak_kv_vnode",
"pid" : "<0.1787.0>"
},
...
]
},
{
"node" : "dev2@127.0.0.1",
"status" : []
},
...
]
}
Permissions required: cluster_observer, cluster_admin.
{"node": NODE}
Initiate node repair on NODE. Node repair can only be started if no repairs are active on any node in the cluster.
On error,
{"error" : "Node exists with ongoing repairs"}
with status code 412.
Permissions required: cluster_observer, cluster_admin.
{
"node" : NODE,
"reason" : REASON
}
Stop node repair on NODE with REASON (a string, which will appear in
console.log as Killing all repairs: REASON).
On success, all requests return 200. On error, the status code will be, depending on cluster condition:
| Condition | Code |
|---|---|
| already_leaving | 409 |
| already_replacement | 409 |
| bad_config | 400 |
| claimant_is_down | 412 |
| invalid_replacement | 409 |
| is_claimant | 409 |
| is_up | 412 |
| nodedown | 412 |
| not_member | 404 |
| not_reachable | 425 |
| not_single_node | 409 |
| only_member | 412 |
| plan_changed | 425 |
| ring_not_ready | 425 |
| self_join | 409 |