Web Console — During Installation

When you are performing the Setup of a new Couchbase Server installation (see Section 2.4, “Setting up Couchbase Server”), you have the option of joining the new node to an existing cluster.

During the first step, you can select the Join a cluster now radio button, as shown in the figure below:

Figure 5.2. Rebalancing — Adding new node during setup

You are prompted for three pieces of information:

The node will be created as a new cluster, but the pending status of the node within the new cluster will be indicated on the Cluster Overview page, as seen in the example below:

Figure 5.3. Rebalancing — Node added during setup

Web Console — After Installation

You can add a new node to an existing cluster after installation by clicking the Add Server button within the Manage Server Nodes area of the Admin Console. You can see the button in the figure below.

Figure 5.4. Rebalancing — Adding new node using the Web Console

You will be presented with a dialog box, as shown below. Couchbase Server should be installed, and should have been configured as per the normal setup procedures. You can also add a server that has previously been part of this or another cluster using this method. The Couchbase Server must be running.

Figure 5.5. Rebalancing — Adding a new node dialog

You need to fill in the requested information:

You will be provided with a warning notifying you 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 added to the cluster, and the servers pending rebalance count will be updated.

Using the REST API

Using 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. For example, using curl you could add a new node:

shell> curl -u cluster-username:cluster-password\
    localhost:8091/controller/addNode \
    -d "hostname=192.168.0.68&user=node-username&password=node-password"

For more information, see Section 8.8.3, “Adding a Node to a Cluster”.

Using the Command-line

You can use the couchbase-cli command-line tool to add one or more nodes to an existing cluster. The new nodes must have Couchbase Server installed, and Couchbase Server must be running on each node.

To add, run the command:

shell> couchbase-cli server-add \
      --cluster=localhost:8091 \
      -u cluster-username -p cluster-password \
      --server-add=192.168.0.72:8091 \
      --server-add-username=node-username \
      --server-add-password=node-password

Where:

If the add process is successful, you will see the following response:

SUCCESS: server-add 192.168.0.72:8091

If you receive a failure message, you will be notified of the type of failure.

Web Console

You can remove a node from the cluster from within the Manage Server Nodes section of the Web Console, as shown in the figure below.

To remove a node, click the Remove Server button next to the node you want to remove. You will be provided with a warning to confirm that you want to remove the node. Click Remove to mark the node for removal.

Using the Command-line

You cannot mark a node for removal from the command-line without also initiating a rebalance operation. The rebalance command accepts one or more --server-add and/or --server-remove options. This adds or removes the server from the cluster, and immediately initiates a rebalance operation.

For example, to remove a node during a rebalance operation:

shell> couchbase-cli rebalance --cluster=127.0.0.1:8091 \
          -u Administrator -p Password \
          --server-remove=192.168.0.73

For more information on the rebalance operation, see Section 5.3.2.3, “Starting a Rebalance”.

Using the Web Console

Within the Manage Server Nodes area of the Couchbase Administration Web Console, a cluster pending a rebalance operation will have enabled the Rebalance button.

Figure 5.6. Rebalancing — Starting a Rebalance

Clicking this button will immediately initiate a rebalance operation. You can monitor the progress of the rebalance operation through the web console. The progress of the movement of vBuckets is provided for each server by showing the movement progress as a percentage.

Figure 5.7. Rebalancing — Monitoring a Rebalance

You can monitor the progress by viewing the Active vBuckets statistics. This should show the number of active vBuckets on nodes being added increased and the number of vBucketson nodes being removed reducing.

You can monitor this through the UI by selecting the vBuckets statistic in the Monitoring section of the Administration Web Console.

You can stop a rebalance operation at any time during the process by clicking the Stop Rebalance button. This only stops the rebalance operation, it does not cancel the operation. You should complete the rebalance operation.

Using the Command-line

You can initiate a rebalance using the couchbase-cli and the rebalance command:

shell> couchbase-cli rebalance -c 127.0.0.1:8091 -u Administrator -p Password
  INFO: rebalancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . .
  SUCCESS: rebalanced cluster

You can also use this method to add and remove nodes and initiate the rebalance operation using a single command. You can specify nodes to be added using the --server-add option, and nodes to be removed using the --server-remove. You can use multiple options of each type. For example, to add two nodes, and remove two nodes, and immediately initiate a rebalance operation:

shell> couchbase-cli rebalance -c 127.0.0.1:8091 \
          -u Administrator -p Password \
          --server-add=192.168.0.72 \
          --server-add=192.168.0.73 \
          --server-remove=192.168.0.70 \
          --server-remove=192.168.0.69

The command-line provides an active view of the progress and will only return once the rebalance operation has either completed successfully, or in the event of a failure.

You can stop the rebalance operation by using the stop-rebalance command to couchbase-cli.