DOC-12187 File based rebalance now supports placing indexes on nodes

modules/introduction/partials/new-features-76_2.adoc

@@ -31,6 +31,13 @@ For details, see xref:javascript-udfs:javascript-functions-with-couchbase.adoc#r
 In deferred build mode, creating an index does not trigger the index build phase: you must trigger the index build before you can use the index.
 For details, see xref:n1ql:n1ql-language-reference/createindex.adoc[CREATE INDEX].
 
+* In Couchbase Server Versions 7.6.0 and 7.6.1, enabling file-based index rebalance prevented you from controlling which Index Service nodes contain an index. 
+Version 7.6.2 removes this restriction.
+You can now use the `WITH <node>` clause of the `CREATE INDEX` {sqlpp} statement when your cluster has file-based index rebalancing enabled.
+See xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[Index Rebalance Methods] for more information.
++
+NOTE: You still cannot use the `WITH <node>` clause with the `ALTER INDEX` statement when your cluster has file-based index rebalancing enabled.
+
 [#search_762]
 === Search Service
 
@@ -57,3 +64,4 @@ Use the xref:n1ql:n1ql-language-reference/searchfun.adoc#search_meta[SEARCH_META
 
 * From version 7.6.2, the Couchbase Server tools package includes the `cbq` shell, alongside the previously-provided tools such as `cbimport`, `cbexport`, and `cbbackupmgr`.
 For details, see xref:cli:cli-intro.adoc#server-tools-packages[CLI Reference].
+

modules/learn/pages/clusters-and-availability/rebalance.adoc

@@ -1,6 +1,7 @@
 = Rebalance
 :description: pass:q[_Rebalance_ redistributes data, indexes, event processing, and query processing among available nodes.]
 :page-aliases: clustersetup:rebalance
+:page-toclevels: 3
 
 [abstract]
 {description}
@@ -150,14 +151,36 @@ The rebalance process takes into account the nodes' CPU, RAM, and disk bandwidth
 By default, Couchbase Server rebuilds the indexes in their new locations during a rebalance.  
 If your cluster uses xref:learn:services-and-indexes/indexes/storage-modes.adoc#standard-index-storage[Standard Index Storage], you can choose to enable file-based rebalance which moves index files between nodes instead of rebuilding them. 
 Copying the index files is faster than having the target node rebuild the index from scratch.
-However, if you enable file-based rebalancing, you lose the ability to choose which Index Service node handles a specific index.  
+You cannot use file-based rebalance if you have enabled xref:learn:services-and-indexes/indexes/storage-modes.adoc#memory-optimized-index-storage[Memory Optimized Index Storage] because this option does not store index metadata in files.
 
-NOTE: The first rebalance after you enable file-based index rebalance does not use the file-based rebalancing method. 
-Instead, the rebalance process rebuilds the indexes. 
-During this rebuild process, Couchbase Server adds metadata to the index files that enables later rebalances to move them between nodes. 
-After this initial rebalance, all later rebalances move the index files as long you as you keep file-base rebalance enabled.
+Couchbase Capella defaults to file-based index rebalance.
 
-If a file-base rebalance fails, you can try starting a new rebalance. 
+To learn how to enable file-based rebalance via the Couchbase Server Web Console, see File Transfer Based Rebalance under xref:manage:manage-settings/general-settings.adoc#index-storage-mode[Index Storage Mode]. To learn how to enable it via the REST API, see the `enableShardAffinity` parameter in xref:rest-api:post-settings-indexes.adoc[].
+
+// Remove after the 7.x series.
+ifeval::['{page-component-version}' == '7.6'] 
+NOTE: In Couchbase Server versions 7.6.0 and 7.6.1, when you enabled file-based rebalance you could not choose which Index Service nodes would contain an index when using the `CREATE INDEX` statement.
+In Couchbase Server 7.6.2 and later, you can use the `WITH <node>` clause to set which node contains the index.
+You still cannot use the `WITH <node>` clause with `ALTER INDEX` after you enable file-based rebalance.
+endif::[] 
+
+===== When File-Based Rebalance Take Effect
+
+The file-based index rebalance method uses metadata in the index's files during the relocation process. 
+When Couchbase Server starts using file-based index rebalance for an index depends on whether the index's files contains this metadata:
+
+* If you enable file-based index rebalance before you create an index, Couchbase Server adds the metadata to the index files while creating them.  
+Because this metadata is in the index's files from the start, the initial rebalance of the index as well as all later rebalances use the file-based rebalance method.
+If you choose to use file-based index rebalance, your best practice is to enable it before you create any indexes.
+
+* If you enable file-based index rebalance after you have created an index, Couchbase Server does not use the file-based rebalance method the next time it rebalances that index. 
+Instead, the next rebalance process still rebuilds the index. 
+During this rebuild, Couchbase Server adds the metadata to the index files to enable file-based rebalance. 
+After this initial rebalance, all later rebalances of the index use the file-based rebalance method.
+
+===== Restarting a Rebalance
+
+If a file-based rebalance fails, you can try starting a new rebalance. 
 The second rebalance does not re-transfer any index that the failed rebalance finished moving. 
 Instead, it moves just the indexes that had not moved or were in the process of moving when the error occurred.  
 

modules/manage/pages/manage-settings/general-settings.adoc

@@ -311,7 +311,7 @@ During an upgrade, mixed mode clusters with nodes that support bloom filters wil
  Once bloom filters are disabled in mixed mode, adding a new 7.2.1{plus} node will not re-enable them.
 // end::bloom-filter-default[]
 
-
+[#file-based-index-rebalance]
 * *File Transfer Based Rebalance*:
 Controls whether Couchbase Server rebuilds indexes or copies them between nodes. 
 The default cleared setting has an Index Server node rebuild any newly assigned index during a rebalance.

modules/rest-api/pages/post-settings-indexes.adoc

@@ -35,7 +35,17 @@ The parameters are specified as key-value pairs (e.g `key=value`).
 | Name | Description | Type
 
 | `enableShardAffinity`
-| Selects the xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[index rebalance method]. When set to the default `false` value, Index Servers rebuild any index that are newly assigned to them during a rebalance. When set to `true`, Couchbase Server moves a reassigned index's files between Index Servers.  
+a| Selects the xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[index rebalance method]:
+
+* `false` (default value): Index Service nodes rebuild indexes that are newly assigned to them during a rebalance.
+* `true`: Couchbase Server moves a reassigned index's files between Index Service nodes.  
+
+// Remove after the 7.x series.
+ifeval::['{page-component-version}' == '7.6'] 
+NOTE: In Couchbase Server versions 7.6.0 and 7.6.1, when you enabled file-based rebalance you could not choose which Index Service nodes would contain an index when using the `CREATE INDEX` statement.
+In Couchbase Server 7.6.2 and later, you can use the `WITH <node>` clause to set which node contains the index.
+You still cannot use the `WITH <node>` clause with `ALTER INDEX` after you enable file-based rebalance.
+endif::[] 
 | boolean
 
 | `indexerThreads`