Skip to content

DOC-12926--8.0--Feedback-on-Nodes--Couchbase-Docs #4092

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RayOffiah merged 3 commits into from
Mar 7, 2026
Merged

DOC-12926--8.0--Feedback-on-Nodes--Couchbase-Docs #4092

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7379874
[DOC-12926]: Feedback on Nodes | Couchbase Docs
RayOffiah Feb 25, 2026
a8c8f69
[DOC-12926]: Feedback on Nodes | Couchbase Docs
RayOffiah Feb 27, 2026
1f891c4
[DOC-12926]: Feedback on Nodes | Couchbase Docs
RayOffiah Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions modules/learn/pages/clusters-and-availability/removal.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ However, removal should be used only when all nodes in the cluster are responsiv
Removal essentially means using xref:learn:clusters-and-availability/rebalance.adoc[Rebalance] to redistribute data across a subset of pre-existing cluster-nodes.
It can be performed with the UI, the CLI, or the REST API.
When the CLI or REST API is used, a single command initiates a rebalance, specifying which nodes are to be excluded.
When the UI is used, nodes to be removed are first identified, then rebalance is initiated.
When the UI is used, nodes to be removed are first identified; then rebalance is initiated.
When the rebalance is complete, the _cluster map_ is correspondingly updated and distributed to clients.
The process occurs while the cluster continues to service requests for data.

Expand Down Expand Up @@ -74,7 +74,7 @@ As Table 1 shows, each of the four nodes takes a roughly equal share of the buck
It also takes a roughly equal share of the replica bucket-items, kept in _replica_ vBuckets.
Since the bucket has two replicas, the ratio of _active_ to _replica_ items, both on each node and in the total for the cluster, is approximately _1:2_.

Table 2 shows the results on the cluster of the removal of node 4 and subsequent rebalance.
Table 2 shows the results on the cluster when node 4 is removed and the cluster is rebalanced.

.Three Surviving Data Service Nodes, One Bucket with 31,591 Items, Two Replicas
[cols="2,3,3"]
Expand Down Expand Up @@ -147,9 +147,25 @@ Note that since multiple buckets may have been configured, and different replica

For further examples of rebalance, in the context of _failover_, see xref:learn:clusters-and-availability/failover.adoc[Failover].

=== Changing the IP address of a node
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new === Changing the IP address of a node subsection is placed under == Removal and Cluster Resources, alongside === Removal Without Replication-Constraint and === Removal With Replication-Constraint. Those sibling sections are about how removal affects data replication and cluster capacity. Changing a node's IP address is a distinct operational procedure and doesn't logically belong under the "Removal and Cluster Resources" heading. Consider making this a separate == level section (e.g., between "Removal and Cluster Resources" and "Removal versus Graceful Failover"), or placing it elsewhere that better fits the topic.

Suggested change
=== Changing the IP address of a node
== Changing the IP address of a node

Copilot uses AI. Check for mistakes.

If you are changing the IP address of a node:

. Remove the node from the cluster.
. Stop the server.
. Change the IP address of the node.
. Remove all the configuration files for the cluster affected by the IP change. The configuration files are located in `/opt/couchbase`. To delete the files, run the terminal command:
+
[source, shell]
----
rm -r /opt/couchbase
----
Comment on lines +152 to +162
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This procedure is Linux-specific (using /opt/couchbase path and rm -r shell command) but doesn't state that it applies only to Linux. Other documentation pages in this codebase (e.g., modules/install/pages/install-uninstalling.adoc) provide platform-specific instructions for Linux, Windows, and macOS. Consider either noting that this procedure is Linux-specific or providing equivalent instructions for other supported platforms.

Copilot uses AI. Check for mistakes.
+
. Restart the server.
Comment thread
RayOffiah marked this conversation as resolved.
Comment on lines +157 to +164
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text says to "Remove all the configuration files" and states they are "located in /opt/couchbase", but the command rm -r /opt/couchbase removes the entire Couchbase Server installation — including binaries, libraries, data, and logs — not just configuration files. This is dangerously misleading.

There's a significant contradiction between the description (remove configuration files) and the command (delete the entire installation directory). If only configuration files need to be removed, the command should target the specific config directory (e.g., /opt/couchbase/var/lib/couchbase/config/), similar to what's done in the Custom Port Mapping docs (modules/install/pages/install-ports.adoc:468-473).

Additionally, if rm -r /opt/couchbase is truly intended, the procedure is incomplete: after deleting the entire installation, the user would need to reinstall Couchbase Server before being able to "Restart the server" in step 5. The procedure also doesn't mention re-adding the node to the cluster after the IP change.

Suggested change
. Remove all the configuration files for the cluster affected by the IP change. The configuration files are located in `/opt/couchbase`. To delete the files, run the terminal command:
+
[source, shell]
----
rm -r /opt/couchbase
----
+
. Restart the server.
. Remove all the configuration files for the cluster affected by the IP change. These are located in the Couchbase configuration directory (for example, `/opt/couchbase/var/lib/couchbase/config/`). To delete the files in this directory, run the terminal command:
+
[source, shell]
----
rm -rf /opt/couchbase/var/lib/couchbase/config/*
----
+
. Restart the server.
. Add the node back to the cluster and rebalance, using the UI, CLI, or REST API.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The procedure ends with "Restart the server" but does not include a step to re-add the node (with its new IP address) back to the cluster. Since step 1 removes the node from the cluster, the user would need to add it back for the IP change to be useful. Consider adding a final step such as "Re-add the node to the cluster using the new IP address" with a cross-reference to the relevant documentation (e.g., xref:manage:manage-nodes/add-node-and-rebalance.adoc).

Suggested change
. Restart the server.
. Restart the server.
. Re-add the node to the cluster using the new IP address. See xref:manage:manage-nodes/add-node-and-rebalance.adoc[Add a Node and Rebalance] for details.

Copilot uses AI. Check for mistakes.

[#removal-versus-graceful-failover]
== Removal versus Graceful Failover

As an alternative to removal, a responsive Data Service node can be taken out of a cluster by means of _Graceful Failover_.
This may be faster, but the consequences do not maintain previous availability-levels.
This may be faster, but the consequences do not maintain previous availability levels.
An account of the advantages and disadvantages is provided in xref:learn:clusters-and-availability/graceful-failover.adoc#advantages-and-disadvantages[Graceful Failover].