Joining Nodes to Clusters
Nodes can be added to clusters with the POST /node/controller/doJoinCluster HTTP method and URI.
Syntax
HTTP request syntax:
POST /node/controller/doJoinCluster Host: localhost:8091 Authorization: Basic xxxxxxxxxxxx Accept: */* Content-Length: xxxxxxxxxx Content-Type: application/x-www-form-urlencoded clusterMemberHostIp=[ip-address]&clusterMemberPort=[port]&user=[admin]&password=[password]
Curl request syntax:
curl -u [admin]:[password] -d clusterMemberHostIp=[ip-address] \ -d clusterMemberPort=[port] \ -d user=[admin] -d password=[password] -d services=[kv | index | n1ql | fts | cbas | eventing | backup] http://[localhost]:8091/node/controller/doJoinCluster
Description
This REST request adds an individual server node to a cluster.
Two clusters cannot be merged together into a single cluster, however, a single node can be added to an existing cluster.
The clusterMemberHostIp and clusterMemberPort parameters must be specified to add a node to a cluster.
To ensure cluster-security, in Couchbase Server Version 7.1.1+, restrictions can be placed on joining, based on the establishment of node-naming conventions. Only nodes whose names correspond to at least one of the stipulated conventions can be joined. For information, see Restrict Node-Addition.
Validating Node Certificates
In Couchbase Enterprise Server Version 7.2+, the node-name must be correctly identified in the node certificate as a Subject Alternative Name. If such identification is not correctly configured, failure may occur when attempting to add or join the node to a cluster. For information, see Node-Certificate Validation.
HTTP method and URI
POST /node/controller/doJoinCluster
The following parameters are required:
| Argument | Description |
|---|---|
clusterMemberHostIp |
Hostname or IP address of a member of the cluster that the node receiving the POST is joining. |
clusterMemberPort |
Port number for the RESTful interface to the system. If the cluster requires credentials, provide the administrator username and password. |
Example
HTTP request example:
POST /node/controller/doJoinCluster Host: 10.5.2.54:8091 Authorization: Basic xxxxxxxxxxxx Accept: */* Content-Length: xxxxxxxxxx Content-Type: application/x-www-form-urlencoded clusterMemberHostIp=192.168.0.1&clusterMemberPort=8091&user=admin&password=admin123
Curl request example:
curl -u Administrator:password -d 'clusterMemberHostIp=192.168.0.1' \ -d 'clusterMemberPort=8091' \ -d 'user=admin' -d 'password=password' \ http://10.5.2.54:8091/node/controller/doJoinCluster
Response codes
200 OK with Location header pointing to pool details of pool just joined - successful join 400 Bad Request - missing parameters, etc. 401 Unauthorized - credentials required, but not supplied 403 Forbidden bad credentials - invalid credentials
When failure results from Certificate Checking, a message of the following form is provided: Attention: Prepare join failed. Unable to validate certificate on host: 127.0.0.1. Please make sure the certificate on this host contains host name '127.0.0.1' in Subject Alternative Name. Refer to Couchbase docs for more info on how to create node certificates.
Restricting the Joining of Nodes
To ensure cluster-security, restrictions can be placed on joining, based on the establishment of node-naming conventions. Only nodes whose names correspond to at least one of the stipulated conventions can be joined. For information, see Restrict Node-Addition.