[PATCH docs v2 19/19] ha-manager: crs: add load balancer section

[Daniel Kral <d.kral@proxmox.com>]

For pve-ha-manager >= 5.2.0, the HA Manager features an automatic
rebalancing system, which is available for the static and dynamic-load
scheduler mode.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Reviewed-by: Dominik Rusovac <d.rusovac@proxmox.com>
---
changes v1 -> v2:
- depending *on* where
- controls the sensitivity of the load balancer

 ha-manager.adoc | 51 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 0421b86..2e13c46 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1435,9 +1435,6 @@ scheduling decisions. The CRS mode can be changed in the web interface
 is `basic`. The change will take effect starting with the next HA Manager
 round, which should take no longer than 10 seconds.
 
-NOTE: There are plans to add modes for (static and dynamic) load-balancing in
-the future.
-
 [[_basic_scheduler]]
 Basic Scheduler
 ^^^^^^^^^^^^^^^
@@ -1526,6 +1523,54 @@ functionality is still in technology preview. The more HA resources the more
 possible combinations there are, so it's currently not recommended to use it if
 you have thousands of HA resources.
 
+CRS Load Balancer
+~~~~~~~~~~~~~~~~~
+
+IMPORTANT: This feature is still in technology preview.
+
+The utilization of individual cluster nodes can vary greatly depending on where
+guests are currently running and how much load these exert at any moment. This
+can cause the node utilizations to become imbalanced over time, where HA
+resources on one node become bottlenecked due to resource contention, while
+another node is barely utilized.
+
+The HA Manager's automatic load balancer can lower the overall cluster
+imbalance by automatically issuing rebalancing migrations. Currently, these
+migrations are issued only for HA resources and executed sequentially.
+Furthermore, these migrations always obey the current HA affinity rules.
+
+The automatic load balancing system can be enabled and configured in the web
+interface under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
+This allows fine-tuning the various parameters as described in the next
+paragraph for different cluster setups and requirements. The load balancer
+requires either the xref:_static_scheduler[static] or
+xref:_dynamic_scheduler[dynamic-load scheduler mode] to be in use.
+
+In every HA Manager round, where each lasts around 10 seconds, the automatic
+load balancer checks whether the cluster imbalance exceeds the _imbalance
+threshold_. If exceeding the imbalance threshold is sustained for at least as
+many consecutive HA Manager rounds as given by the _hold duration_, then the
+load balancer will select the rebalancing migration for an HA resource, which
+lowers the overall cluster imbalance the most. The method used to select the
+best rebalancing migration can be set with the _rebalancing method_ option. At
+last, if the selected migration reduces the current cluster imbalance by at
+least the percentage given by the _imbalance improvement_ option, the load
+balancer issues the selected migration.
+
+The cluster imbalance is calculated as the ratio between the standard deviation
+and mean of the individual node loads. Therefore, the _imbalance threshold_
+controls the sensitivity of the load balancer. If the _imbalance threshold_ is
+set to a value of `0.0`, it will try to select a rebalancing migration every
+time the _hold duration_ is exceeded. The _imbalance improvement_ percentage
+filters what constitutes as an acceptable rebalancing migration. If it is set
+to `0.0`, then it will always commit to a migration even though the expected
+imbalance does not change at all. However, the value can never be negative,
+therefore it will never commit to a migration with an expected imbalance worse
+than the current one.
+
+NOTE: It is planned that load balancing will also include non-HA resources in
+the future.
+
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
 endif::manvolnum[]
-- 
2.47.3