--- title: Upgrade a Full-Capacity, Online Cluster pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-server/edit/release/8.0/modules/install/pages/upgrade-cluster-online-full-capacity.adoc xref: xref:server:install:upgrade-cluster-online-full-capacity.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/current/install/upgrade-cluster-online-full-capacity.html) # Upgrade a Full-Capacity, Online Cluster > A cluster can be upgraded while still online, and maintained at full capacity. ## [](#online-upgrade-with-full-capacity)Understanding Full-Capacity Upgrade The context and overall requirements for upgrading a live cluster by means of the introduction of one or more additional nodes are described in [Upgrade-Procedure Selection](upgrade-procedure-selection.md): this fully explains the node-by-node upgrade of the cluster, using _swap rebalance_ to minimize overhead. It also explains how, if additional nodes are available, the cluster is maintained at full capacity during the upgrade. The precise steps for this procedure are detailed on this page, below. A full understanding of the information in [Upgrade-Procedure Selection](upgrade-procedure-selection.md) should be acquired, before proceeding. The procedure assumes that: * The cluster to be upgraded must continue to serve data throughout the cluster-upgrade process. * A single, additional node is available; to act as a _swap_ node. The node _either_ has not previously run Couchbase Server, _or_ has run a version that can, with all its configuration files and other data, be overwritten: therefore, the latest version of Couchbase Server will be installed on the node. (Prior to installation, if necessary, remove any old configuration files from `/opt/couchbase`, using the command `rm -r /opt/couchbase`.) * During the cluster-upgrade process, _swap_ nodes and _upgraded_ nodes will be introduced to the cluster by the _node-addition_ procedure; while _failed over spare nodes_ and _nodes to be upgraded_ will be withdrawn from the cluster by means of the _node removal_ and _swap rebalance_ procedures. For information on node-addition, see [Clusters](../learn/clusters-and-availability/nodes.md#clusters). For information on node-removal, see [Removal](../learn/clusters-and-availability/removal.md). For information on _swap rebalance_, see [Swap Rebalance](upgrade-procedure-selection.md#swap-rebalance). * Nodes will be upgraded _one at a time_. > [!NOTE] > Running Eventing functions during a rolling upgrade increases rebalance duration. To reduce rebalance time, pause all your Eventing functions before starting the upgrade, and resume them after the upgrade completes. The overall procedure is described in seven stages, below. ## [](#prepare-a-spare-node)Stage One: Prepare a Spare Node Install the latest version of Couchbase Server on the spare node. For instructions, see [Install](install-intro.md); and follow steps 1, 2, and 3. ## [](#prepare-the-cluster)Stage Two: Prepare the Cluster Back up all cluster-data. This is performed either with [cbbackupmgr](../backup-restore/enterprise-backup-restore.md) or with the [Backup Service](../learn/services-and-indexes/services/backup-service.md); and must be a _full_ (rather than an incremental) backup. For example, to use `cbbackupmgr` to configure an archive and repository for the backup, a command of the following form should be entered: ```bash cbbackupmgr config --archive ${ABS_PATH_TO_ARCHIVE} --repo ${REPO_NAME} ``` Here, `ABS_PATH_TO_ARCHIVE` is an absolute path to a filesystem location that will serve as the archive within which the backed up data will reside. The `REPO_NAME` is the name of the repository that will be associated with the location. Once the archive and repository have been created, a command such as the following performs a full backup: ```bash cbbackupmgr backup --archive ${ABS_PATH_TO_ARCHIVE} --repo ${REPO_NAME} \ --cluster ${CLUSTER_ADDRESS} --username ${USERNAME} --password ${PASSWORD} \ --full-backup ``` Here, the `CLUSTER_ADDRESS` is the IP address or domain name of the cluster that is being backed up. The `--full-backup` flag ensures that the backup is indeed a _full_ backup. For the equivalent procedure as performed by the Backup Service, see [Run an Immediate Backup](../manage/manage-backup-and-restore/manage-backup-and-restore.md#run-an-immediate-backup). ## [](#add-and-remove-a-node)Stage Three: Add the Spare Node, and Remove a Node _Add_ the upgraded, removed node back into the cluster, and _remove_ a node that is currently part of the cluster. The node that is being added should be configured to run the same service (or services) as on the node that is to be removed. For example, if the node to be removed is running the Data Service, configure the node to be added to run the Data Service. Couchbase Server will execute the rebalance as a _swap rebalance_, to maximize efficiency. For an overview of node-removal, see [Removal](../learn/clusters-and-availability/removal.md); and for practical examples of performing removal, see [Clusters](#manage:manage-nodes/remove-node-and-rebalance.adoc. For an overview of node-addition, see xref:learn:clusters-and-availability/nodes.html#clusters); and for practical examples of node-addition, see [Add a Node and Rebalance](../manage/manage-nodes/add-node-and-rebalance.md). Note that for the CLI and REST API, the staging of a swap rebalance requires _two_ separate commands. * The first specifies that one or more nodes be _added_ to the cluster: however, this command requires a subsequent rebalance to be performed, to complete the process. For an example of performing addition with the CLI, see [Add a Node and Rebalance with the CLI](../manage/manage-nodes/add-node-and-rebalance.md#add-a-node-with-the-cli). For an example of performing addition with the REST API, see [Add a Node and Rebalance with the REST API](../manage/manage-nodes/add-node-and-rebalance.md#add-a-node-with-the-rest-api). * The second command indeed specifies that subsequent rebalance, but also includes an instruction to _remove_ one or more nodes from the cluster: therefore, as the rebalance occurs, it finalizes both node-addition and node-removal. For an example of using rebalance to remove a node with the CLI, see [Remove a Node with the CLI](../manage/manage-nodes/remove-node-and-rebalance.md#remove-a-node-with-the-cli). For an example of using rebalance to remove a node with the REST API, see [Remove a Node with the REST API](../manage/manage-nodes/remove-node-and-rebalance.md#remove-a-node-with-the-rest-api). ## [](#upgrade-the-removed-node)Stage Four: Upgrade the Removed Node Upgrade the node that has just been removed, by proceeding as follows: 1. Stop the `couchbase-server.service` service, on the node. Enter the following command: ```bash systemctl stop couchbase-server.service ``` This _stops_ the service; and so allows it to be restarted after reboot. Note that, optionally, at this point, the service can also be _disabled_; which prevents it from restarting after reboot. This may be useful if additional tasks, such as OS upgrade, need to be performed. If such disabling is desired, enter the following command: ```bash systemctl disable --now couchbase-server.service ``` 2. Back up the configuration files for the removed node. On a Linux system, these files are to be found in `/opt/couchbase/var/lib/couchbase/config`. Ideally, these should be backed up onto a different machine. The command takes the following form: ```bash cp -r /opt/couchbase/var/lib/couchbase/config ${PATH_TO_A_SAFE_LOCATION}/${NODE_IP}_config_files ``` 3. Uninstall `couchbase-server` and its dependencies from the removed node. Enter the command that is appropriate for the platform. Note that the following examples remove _Enterprise Edition_ of Couchbase Server: to remove _Community Edition_, specify `couchbase-server-community` (instead of `couchbase-server`). * Red Hat-based distributions * Ubuntu & Debian ```bash yum autoremove couchbase-server ``` ```bash apt autoremove --purge couchbase-server ``` 4. Manually remove files from `/opt/couchbase`. This folder contains configuration files for the previous server-version; which need to be overwritten by configuration files for the new version. If the administrator has manually included in this folder any files that were not provided by Couchbase Server, and need to be retained, these should be individually identified and backed up with with [cbbackupmgr](../backup-restore/enterprise-backup-restore.md) or with the [Backup Service](../learn/services-and-indexes/services/backup-service.md). Note also that care should taken regarding the potential removal of files used in network sharing. Enter the following command: ```bash rm -r /opt/couchbase ``` 5. Determine whether any other files, still resident on the node, need to be either removed, or backed up and removed. If such files exist, deal with them accordingly. 6. Install Couchbase Server on the node. Follow steps 1, 2, and 3; provided in [Install](install-intro.md). 7. _Pin_ (or _hold_) automated Couchbase-Server updates for the node. This ensures that no further upgrade can occur to this node until the next time the administrator electively performs the process. Red Hat-based distributions For Couchbase Server Enterprise Edition, ensure that the package-name appears in the list that follows the `exclude` statement, in the file `/etc/yum/yum.conf`. For example: ```bash exclude=couchbase-server ``` (For Couchbase Server Community edition, specify `couchbase-server-community`, instead of `couchbase-server`). Ubuntu & Debian For Couchbase Server Enterprise Edition, run the following command: ```bash apt-mark hold couchbase-server ``` (For Couchbase Server Community edition, specify `couchbase-server-community`, instead of `couchbase-server`). 8. Assuming that the `couchbase-server.service` service was _stopped_ on the node to be upgraded prior to that node's upgrade, restart the service. Note that if the service was also _disabled_, it must be _re-enabled_, prior to being started. To re-enable the service, if necessary, enter the following command: ```bash systemctl enable --now couchbase-server.service ``` To restart the service, enter the following command: ```bash systemctl start couchbase-server.service ``` ## [](#add-back-the-upgraded-node-and-remove-another-node)Stage Five: Add Back the Upgraded Node, and Remove Another Node _Add_ the upgraded, removed node back into the cluster, and _remove_ a node that is currently part of the cluster. The node that is being added should be configured to run the same service as that running on the node that is to be removed. For example, if the node to be removed is running the Data Service, configure the node to be added to run the Data Service. Couchbase Server will execute the rebalance as a _swap rebalance_, to maximize efficiency. ## [](#repeat-stages-three-and-four)Stage Six: Continually Repeat Stages Four and Five Upgrade the newly removed node as described above, in [Stage Four: Upgrade the Removed Node](#upgrade-the-removed-node). Then, add the upgraded node back into the cluster, and remove another node to be upgraded: as described above, in [Stage Five: Add Back the Upgraded Node, and Remove Another Node](#add-back-the-upgraded-node-and-remove-another-node). Continue to remove, upgrade, and restore nodes in this way; until the cluster is fully upgraded, and only the spare node remains outside the cluster. ## [](#add-back-the-last-node)Stage Seven: Repurpose the Spare Node Once the cluster has been fully upgraded, the spare node can be repurposed. This concludes the overall cluster-upgrade process.