[pve-devel] [PATCH ha-manager v4 21/21] rules: add documentation about current feasibility check implementations

[Daniel Kral]

These notes should clarify the goals and reasons for the feasibility
checks while giving direction how these can be improved in the future.

Signed-off-by: Daniel Kral <d.kral at proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl at proxmox.com>
Tested-by: Michael Köppl <m.koeppl at proxmox.com>
---
 src/PVE/HA/Rules.pm | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/PVE/HA/Rules.pm b/src/PVE/HA/Rules.pm
index 9d7f12a1..c4a2ccea 100644
--- a/src/PVE/HA/Rules.pm
+++ b/src/PVE/HA/Rules.pm
@@ -32,6 +32,13 @@ the feasibility between rules of the same type and and between rules of
 different types, and prune the rule set in such a way, that it becomes feasible
 again, while minimizing the amount of rules that need to be pruned.
 
+The feasibility checks must verify that all rules can be applied error-free in
+any runtime state of the HA resources, cluster nodes, and the HA Manager in a
+reasonable amount of time. This might require more rules to be rejected than
+necessary as some checks can become computationally expensive for little benefit
+to the core feature, but this can certainly be reevaluated if there are user
+requests for these cases.
+
 More so, the rules given by the config file might not be in the best format to
 be used internally or does not contain the implicitly stated rules, which are
 induced by the relationship between different rules. Therefore, this package
@@ -598,9 +605,11 @@ a list of lists, each consisting of the rule type and rule id, where at
 least one resource in a resource affinity rule is in a node affinity rule,
 which has multiple priority groups defined.
 
-That is, the resource affinity rule cannot be statically checked to be feasible
-as the selection of the priority group is dependent on the currently online
-nodes.
+These cases are currently rejected, because the selection of the highest
+priority class is dependent on the currently online nodes and on the current
+HA resource states and node placements in the case of negative resource affinity
+rules. This makes the verification of these rules' feasibility in all possible
+states computationally hard.
 
 If there are none, the returned list is empty.
 
@@ -670,6 +679,10 @@ lists, each item consisting of the rule type and rule id, where at least one of
 the resources is used in a positive resource affinity rule and more than one
 node affinity rule.
 
+These cases are currently rejected, because there is no definitive method to
+merge multiple node affinity rules, e.g. with different strictness values and
+different priority classes, yet.
+
 If there are none, the returned list is empty.
 
 =cut
-- 
2.47.3