Identifying the Orchestrator Node

The node currently running the orchestrator (sometimes referred to as the Master Services) can be identified by means of the REST API.

HTTP Method and URI

GET /pools/default/terseClusterInfo

Description

The orchestrator handles operations with cluster-wide impact; such as failover, rebalance, and adding and deleting buckets. Every Couchbase-Server node contains an instance of the orchestrator. However, at any given time, on a multi-node cluster, only one instance of the orchestrator, on one particular node, is active; and thereby responsible for performing all the cluster-wide operations. If a hitherto active instance becomes unavailable, another instance, on another node, takes over.

The GET /pools/default/terseClusterInfo http method and URI identify the node on which the active orchestrator currently resides.

For more information on the orchestrator and the cluster manager, see Cluster Manager.

This http method and URI are available in Couchbase Server Version 6.6.1 and later.

Curl Syntax

curl -v -X GET -u <username>:<password>
  http://<ip-address-or-domain-name>:8091/pools/default/terseClusterInfo

The ip-address-or-domain-name should specify a node within the cluster whose orchestrator-location is to be determined: information returned by the call is that which is known to the specified node. The username and password must be those of a user with the Full Admin, Cluster Admin, Read Only Admin, Local User Security Admin, or External User Security role.

Responses

Success returns 200 OK, and an object that contains the following key-value pairs:

clusterUUID. The universally unique identifier of the cluster whose orchestrator-node is being returned.
orchestrator. A reference to the node on which the orchestrator is believed, by the specified node, to be running at the time the call is executed. This value is "undefined" if, for any reason, the specified node is unaware of the orchestrator-location. In particular, if the orchestrator node is rebalanced out, the value of this attribute will be "undefined" during the time-period that starts immediately after the node is rebalanced out, and lasts until a new orchestrator is elected: this period is 10 seconds in duration.

Note that the location of the orchestrator may change at any time, including at a point subsequent to execution of the call but prior to the return of a value; meaning that the returned value is already incorrect. Note also that in cases where the cluster has undergone an unexpected network partition, different specified nodes may return different values.
isBalanced. The value is true if the specified node believes that data is distributed evenly, topology-aware services are in balance, and no rebalance is required. Otherwise, the value is false.
clusterCompatVersion. The minimum Couchbase-Server compatibilty version for the cluster. For example, if a cluster of ten nodes has eight running Couchbase Server Version 6.6, and two running 6.0, the returned clusterCompatVersion value is "6.0".

Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found.

Example

The following example returns the orchestrator-location for a cluster that includes a node whose IP address is 10.143.210.102. Note that the output is piped to the jq command, to facilitate readability:

curl -v -X GET -u Administrator:password \
http://10.143.210.102:8091/pools/default/terseClusterInfo | jq '.'

If the call is successful, 200 OK is returned, with the following output:

{
  "clusterUUID": "21d1c9a5d1f40f5bb8ac73f6df9db8a7",
  "orchestrator": "ns_1@10.143.210.101",
  "isBalanced": true,
  "clusterCompatVersion": "6.6"
}

The output thus provides the UUID of the cluster, and the orchestrator-location (which is the node whose IP address is 10.143.210.101). It also verifies that the cluster currently does not require rebalance, and that its minimum compatibility version is 6.6.