A newer version of this documentation is available.

View Latest

Joining Nodes to Clusters

  • reference
    +
    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:

    Table 1. /node/controller/doJoinCluster parameters
    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.