A newer version of this documentation is available.

View Latest
January 5, 2025
+ 12
Nodes are added to clusters with the POST /controller/addNode HTTP method and URI.

HTTP method and URI

POST /controller/addNode

Description

This adds a server node to the cluster. One or more services can be specified to run on the added node. These are kv (data), index (index), n1ql (query), eventing (eventing), fts (search), cbas (analytics), and backup (backup). If no services are specified, the Data Service is enabled by default.

Curl Syntax

curl -u [admin]:[password]
  http://[localhost]:8091/controller/addNode
  -d hostname=[IPaddress]
  -d user=[username]
  -d password=[password]
  -d services=[kv|index|n1ql|fts|cbas|eventing|backup]

Note that the administrative username and password must be specified. If the new node has not yet been provisioned, placeholder names must be provided.

Responses

Success gives 200 OK, and returns an object of the form {"otpNode":"ns_1@ip-address-of-added-node"}, to confirm that the node has been added. Specifying an unknown service gives 400 Bad Request, and an object of the form ["Unknown services: [\"unknown-service-name\"]"]. If the node to be added has already been provisioned, and its administrative credentials are not properly specified, 400 Bad Request is given, and an object is returned of the form ["Prepare join failed. Authentication failed. Verify username and password."]

If the IP address of the new node is not accurately specified, or otherwise cannot be reached, 400 Bad Request is given, and an object is returned of the form ["Failed to reach erlang port mapper at node \"ip-address-of-new-node\". Error: ehostunreach"]. If the IP address of the host cluster is not accurately specified, or otherwise cannot be reached, the request times out, giving Empty reply from server. Failure to authenticate with the cluster gives 401 Unauthorized.

Example

The following example adds a server node, 10.143.190.103, to the cluster at 10.143.190.101:8091, establishing the Data, Query, and Index Services on the new node. The IP address for the new server and its administrative credentials are provided.

curl -v -X POST -u Administrator:password \
http://10.143.190.101:8091/controller/addNode \
-d 'hostname=http://10.143.190.103' \
-d 'user=Administrator' \
-d 'password=password' \
-d 'services=kv,n1ql,index'

If successful, Couchbase Server responds as follows, identifying the node that has been added:

{"otpNode":"ns_1@10.2.2.64"}

Subsequent to addition, the node must be rebalanced into the cluster. See Rebalancing the Cluster.

See Also

For a conceptual overview of nodes, including options for adding nodes to clusters, see Nodes. For information on rebalancing, see Rebalancing the Cluster. For information on adding nodes and rebalancing by means of Couchbase Web Console and the CLI, see Add a Node and Rebalance.