What you will learn
A Couchbase node can host Data, Index, Query, Search, or other services. The procedure must protect each service, not just bucket item counts. Package versions and permitted transitions depend on the exact edition and release.
Before you begin
Use a multi-node lab with a recorded service layout, bucket replicas, server groups, healthy indexes, and enough spare capacity. Confirm the current/target compatibility matrix and SDK support. Take a backup with tooling available for your edition and prove its restore into a separate lab; the absence of a preferred backup tool is not permission to skip recovery planning.
1. Inventory the current service
In the web console, record Servers, bucket health and replica settings, index status, and any XDCR relationships. Check disk and memory headroom. Identify single-instance services that could cause interruption even when data replicas remain available.
2. Choose the transition
For a healthy node, use removal and rebalance so its responsibilities move while it is available. A failed-over node is a different recovery case. For replacement, a new clean node can support a swap-rebalance plan when the release and service topology allow it.
3. Prepare the change window
Pause conflicting maintenance and capture the current monitoring/automatic-failover policy. Retain observability during the operation. If the version-specific procedure requires a temporary policy change, record both the old value and the restoration step. Rehearse application retries and expected interruption.
4. Perform one controlled transition
In Servers, choose the intended node for removal and review the resulting topology before starting rebalance. Wait for completion and inspect any rebalance errors. For a reinstall, only then stop/rebuild the retired host and introduce it as a clean node using the supported join procedure.
5. Check service readiness before the next node
Wait for balanced data placement and service health. Run key-value reads/writes and representative SQL++ queries; verify indexes and Search/XDCR where used. A green Data service does not prove all query-serving components are ready. Repeat only after the canary meets the agreed thresholds.
Example output
The following is an illustrative, normalized lab result, not output captured from a live customer system. Your versions, addresses, timings, and row counts will differ.
Illustrative console acceptance record:
Rebalance: completed
Expected server inventory: matches plan
Data replicas: healthy
Required indexes: online
Key-value test: passed
Representative SQL++ query: passed
These are observations to collect from the console and application test, not a command transcript. Rebalance completion alone cannot validate a service that was never exercised.
Verify the result
The final node/version inventory matches the plan, replicas are healthy, rebalance has completed, and each hosted service passes its own test. Compare application errors and latency with the baseline. Restore any deliberately changed maintenance policy.
Troubleshooting
A stalled rebalance needs its task/error details, destination disk capacity, and service topology reviewed. Missing replicas mean the cluster cannot be considered protected yet. Query failures can be caused by unavailable indexes or incompatible SDK behavior rather than missing documents.
Recovery and next steps
Keep the pre-change backup and retired-node recovery evidence until acceptance. Do not assume a newer data directory can be opened by older binaries. If the canary fails, stop progression, restore the previous service path where supported, or use the verified restore procedure.