Upgrade Guide Reorganization - Recommendations ---------------------------------------------- [Overall: Most of the necessary information is already present, but its organization can be improved. Some duplication can be eliminated. Some diagrams can be introduced to emphasize the difference between the procedures. Existing install routines should be more explicitly referenced.] Introduction to Upgrade ----------------------- Upgrade is one of the following processes: * A cluster that has been running an earlier version of Couchbase Server Enterprise Edition or Community Edition is modified to run a later version of the same edition. * A cluster that has been running Couchbase Server Community Edition is modified to run the same version Couchbase Server Enterprise Edition. Upgrade has the following, principal characteristics: - Upgrade occurs one node at a time, during which the node is not a functioning part of any cluster. - In most cases (but not all), upgrade simply means performing a standard install on the updated Couchbase-Server package, without an uninstall of the old package being required. - Upgrade can be performed either with the cluster continuing to serve data, or with the cluster taken entirely offline until the conclusion of the upgrade process. If the cluster continues to serve data during the process, nodes must be removed, upgraded, and re-introduced one at a time. If the server is to be taken entirely offline, Cross Data-Center Replication can optionally be used prior to the upgrade process, to equip an alternative cluster with the required data: the alternative cluster can then continue the serving of data while to principal cluster undergoes its offline upgrade. - Every node in the cluster must be upgraded to the same version of Couchbase Server. If the cluster continues to serve data during the node-by-node upgrade, the features of the new server-version are in most cases not available to be used until the upgrade's conclusion. Upgrade Paths and Latest Features --------------------------------- Upgrade Path Tables Latest Feature Upgrade Table Cluster-Online Upgrade and Maintenance -------------------------------------- [Note: Although these routines are for upgrade, they are surely valid also for all kinds of node-maintenance. So I believe it's worth pointing out that they should be used in circumstances other than upgrade, also.] If the cluster continues to serve data during the process, nodes must be removed, upgraded, and re-introduced one at a time. Such ongoing changes to the cluster require rebalance to be performed repeatedly, either by: * Remove and rebalance This may be costly, especially when Data Service nodes are affected, since replica-numbers must be recomputed and redistributed whenever the number of nodes in the cluster falls or rises. * Swap rebalance This may be more efficient, since it involves, as much as is practically possible, the removal of a node to be upgraded at the same time that a newly upgrade node is being re-introduced: this restricts the complexity of the rebalance that must occur. However, the first step must always involve a single node: either one that is removed on its own, or one that is introduced as an extra node, so that the cluster's total node-count is never diminished below the established level. [Show the above with sequential diagrams.] Procedures: 1. Remove and rebalance, step by step. 2. Swap rebalance, step by step. [For each procedure, when the actual Upgrade of the node occurs, link to the Upgrade procedure table.] Cluster-Offline Upgrade and Maintenance --------------------------------------- Basic prospectus: 1. Take cluster offline. 2. Upgrade all nodes. 3. Put cluster back online. Safe cluster-shutdown is therefore essential. [Break the current numbered list into sections.] 1. Cluster shutdown (auto-failover, applications, backup, queue-drain) 2. Upgrade (shut down cb, upgrade link, monitor warmup) 3. Bring back online. Using XDCR - notes on setting up bi-directional replication. Notes on app switching. (How much, I wonder, can really say about this difficult area?) [Single node backup. Do we need a page for this? Why is it different? I do notice that we specifically say "back up cb server config files". Should we be saying this explicitly elsewhere? I think we can just put a note on an existing page, to say that the instructions are basically the same as for a node in a multi-node cluster.] Upgrade procedure table ----------------------- A table for each platform. The upgrade procedure is represented by a link, which takes the reader to the exact subset of "Install" instructions that must be performed for the upgrade. (This means we don't have to repeat the instructions, but can still emphasize that they are the same as for install. On MacOS, we will likely have to point first to the uninstall, then to the install.) Upgrading IPV6 Clusters ----------------------- Stays the same.