DOC-13858 Server File-Based Rebalance for Data Service

[rao-shwe]

This is my reformatting/editing of Schewtha's draft of the FBR docs.

Important Note: This draft does not contain documentation for the Web Console's FBR settings. The UI wasn't ready when this draft was written and revised. This draft is mainly for review before inclusion before the early Totoro release. Other features are taking prioority over getting the GUI documentation done.

Cribbing CoPilot's summary of these changes:

Adds documentation for the new Data Service File-Based Rebalance (FBR) feature in Couchbase Server Totoro, including a new REST API reference page, navigation entry, conceptual coverage in the rebalance learn page, a new bucket-level dataServiceRebalanceType parameter, and updates to general settings, node management, and the 8.1 new-features page. Also performs cosmetic cleanup (removing italic emphasis) in the rebalance learn page and updates the shared user/pwd/host/port REST parameter partial.

Changes (with links to the preview):

You will need the Docs Team credentials on Confluence to view the preview.

• New REST reference page file-based-data-rebalance.adoc documenting GET/POST /internalSettings usage for FBR, plus nav and rebalance-table entries.
• New dataServiceRebalanceType bucket parameter documentation added to rest-bucket-create.adoc, with cross-references from general settings, add-node-and-rebalance, and the rebalance learn page.
• Conceptual FBR section added to rebalance.adoc and a Totoro new-features entry, plus formatting cleanup of italic markers across rebalance.adoc and rest-rebalance-overview.adoc.

[Copilot]

Pull request overview

Adds documentation for the new Data Service File-Based Rebalance (FBR) feature in Couchbase Server 8.1, including a new REST API reference page, navigation entry, conceptual coverage in the rebalance learn page, a new bucket-level dataServiceRebalanceType parameter, and updates to general settings, node management, and the 8.1 new-features page. Also performs cosmetic cleanup (removing italic emphasis) in the rebalance learn page and updates the shared user/pwd/host/port REST parameter partial.

Changes:

• New REST reference page file-based-data-rebalance.adoc documenting GET/POST /internalSettings usage for FBR, plus nav and rebalance-table entries.
• New dataServiceRebalanceType bucket parameter documentation added to rest-bucket-create.adoc, with cross-references from general settings, add-node-and-rebalance, and the rebalance learn page.
• Conceptual FBR section added to rebalance.adoc and a 8.1 new-features entry, plus formatting cleanup of italic markers across rebalance.adoc and rest-rebalance-overview.adoc.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
modules/ROOT/nav.adoc	Adds new FBR REST page to the navigation.
modules/rest-api/partials/user_pwd_host_port_params.adoc	Renames placeholders to uppercase (HOST, PORT, USER, PASSWORD).
modules/rest-api/partials/rest-rebalance-table.adoc	Adds GET/POST /internalSettings rows for FBR.
modules/rest-api/pages/rest-rebalance-overview.adoc	Removes italic emphasis from prose.
modules/rest-api/pages/rest-bucket-create.adoc	Documents new dataServiceRebalanceType bucket parameter with examples.
modules/rest-api/pages/file-based-data-rebalance.adoc	New REST reference page for configuring FBR via /internalSettings.
modules/manage/pages/manage-settings/general-settings.adoc	Adds description of the new FBR concurrent-moves UI setting.
modules/manage/pages/manage-nodes/add-node-and-rebalance.adoc	Adds note that FBR is used automatically during node addition (EE).
modules/learn/pages/clusters-and-availability/rebalance.adoc	Adds conceptual FBR section and removes italic emphasis throughout.
modules/introduction/partials/new-features-81.adoc	Adds the FBR entry under Data Service new features.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[hyunjuV]

1. The info about File-Based Rebalance throttle rate setting snapshot_download_throttle_bytes should be added, along with metric kv_ep_snapshot_read_bytes that can be monitored to view the throughput.

2. The rest of the comments were mostly about where the phrasing/text suggests that rebalance type decision is made for each vBucket (not true) and that rebalance type decisions are made for scenarios like when either file-based or DCP rebalance is likely to perform x percent faster than the other or if all data is 100% memory resident, etc (not true as far as I'm aware, but should double check with Ben Huddleston).

While true that for ephemeral buckets, there's no backfill phase (so, no file-based rebalance), for non-ephemeral buckets, memory residency is not considered in the decision to do file-based rebalance or DCP rebalance (I do not believe).

[Copilot]

Pull request overview

Copilot reviewed 13 out of 17 changed files in this pull request and generated 17 comments.

Comments suppressed due to low confidence (1)

modules/rest-api/pages/file-based-data-rebalance.adoc:125

• The POST section uses a different path-parameter partial (user-pw-host-port-params) than the GET section (user_pwd_host_port_params), which leads to inconsistent placeholder naming (host/port vs HOST/PORT) within the same page. It also sets :priv-link: even though the curl syntax uses ${HOST}/${PORT}.

=== Path Parameters
:priv-link: settings-privs
include::partial$user-pw-host-port-params.adoc[]

[ggray-cb]

OK, I think I've addressed all comments and missing pieces from the original draft. I've updated the preview site with the latest draft.