A newer version of this documentation is available.

View Latest

Adding a Node

    Add a node to the cluster during initial installation or after the installation.

    Full Administrators and Cluster Administrators can use the UI, CLI, or REST API interface to add a node.

    There are several methods for adding a node to a cluster. In each case, one or more nodes are marked to be added to the cluster, but it doesn’t become an active member of the cluster until you rebalance the cluster.

    In a CLI call, the rebalance can optionally be done while adding the new node and using the UI, rebalancing requires an extra step.

    Note that the examples in this section assume that no node is certificate-protected. If certificate-protection has been applied to a cluster, all new nodes to be incorporated into that cluster must themselves be appropriately certificate-protected before incorporation is attempted: this means that the chain certificate chain.pem and the private node key pkey.key must be in the /opt/couchbase/var/lib/couchbase/inbox/ folder, for each cluster-node. For information on certificate-preparation, see X.509 for TLS.

    During Initial Installation

    When setting up a new Couchbase Server installation, you have the option to join the new node to an existing cluster. For detailed instructions, see Initializing the Cluster.

    The node will be created as a new cluster, but the pending status of the node within the new cluster will be indicated, as shown in the example below:

    admin tasks rebalance node added

    Using the UI

    Using the same method, you can add a server that was previously part of this or another cluster. During this process, Couchbase Server must be running.

    add server new2

    To add a new node to an existing cluster using the Web Console:

    1. From the Couchbase Web Console > Servers > click Add Server.

    2. Enter the following information and click Add Server.

    Option Description

    Server IP Address

    The IP address or FQDN (Fully Qualified Domain Name) of the server that you want to add. It is preferred that you use FQDNs, especially in a cloud hosting environment.

    Assign Server Group

    Select the server group name from the list. For more information about server groups, see Managing Server Groups.


    The username of the administrator account of the node to be added.


    The password of the administrator account of the node to be added.


    Select the appropriate check box to define the kind of services will be provided on the server node that’s been added. You can add one or more services. The options are: Data, Query, Index, Search, Analytics, and Eventing.

    A warning will appear indicating that the operation is destructive on the destination server. Any data currently stored on the server will be deleted, and if the server is currently part of another cluster, it will be removed and marked as failed over in that cluster.

    Once the information has been entered successfully, the node will be marked as ready to be added to the cluster, and the cluster’s pending rebalance count will be updated.

    Once a node is added with a specific service, you cannot change the type of services on that node. You must remove the node, rebalance, and then add it back to the cluster with the services of your choice.

    Adding Multiple Nodes

    When the routine for adding nodes is used to increment a cluster with multiple nodes simultaneously, the additions should all be executed on a single node of the cluster: this simplifies the reconfiguration process, and so protects against error.

    Using the CLI

    The Couchbase CLI can be used to add one or more nodes to an existing cluster. See the server-add command. See also the rebalance command, which must be used after the nodes have been added.

    Using the REST API

    With the REST API, you can add nodes to the cluster, by providing the IP address, administrator username, and password as part of the data payload. See Adding Nodes to Clusters, for information. Also, see Rebalancing Nodes, for information on how to rebalance the cluster with the REST API, following node-addition.