Update design document and man pages

* Actualize instance pinning documentation in the location design document
* Add instance pinning documentation to the hbal man page.
Signed-off-by: Oleg Ponomarev <onponomarev@gmail.com>
Signed-off-by: Klaus Aehlig <aehlig@google.com>
Reviewed-by: Klaus Aehlig <aehlig@google.com>

doc/design-location.rst

@@ -121,8 +121,15 @@ failure tag. Those tags indicate the the instance wants to be placed on a
 node tagged *x*. To make ``htools`` honor those desires, the metric is extended,
 appropriately weighted, by the following component.
 
-- The number of instances tagged *htools:desiredlocation:x* where their
-  primary node is not tagged with *x*.
+- Sum of dissatisfied desired locations number among all cluster instances.
+  An instance desired location is dissatisfied when the instance is assigned
+  a desired-location tag *x* where the node is not tagged with the location
+  tag *x*.
+
+Such metric extension allows to specify multiple desired locations for each
+instance. These desired locations may be contradictive as well. Contradictive
+desired locations mean that we don't care which one of desired locations will
+be satisfied.
 
 Again, instance pinning is just heuristics, not a hard enforced requirement;
 it will only be achieved by the cluster metrics favouring such placements.

man/hbal.rst

@@ -139,6 +139,8 @@ following components:
 - standard deviation of the CPU load provided by MonD
 - the count of instances with primary and secondary in the same failure
   domain
+- the overall sum of dissatisfied desired locations among all cluster
+  instances
 
 The free memory and free disk values help ensure that all nodes are
 somewhat balanced in their resource usage. The reserved memory helps
@@ -147,8 +149,8 @@ instances, and that no node keeps too much memory reserved for
 N+1. And finally, the N+1 percentage helps guide the algorithm towards
 eliminating N+1 failures, if possible.
 
-Except for the N+1 failures, offline instances counts, and failure
-domain violation counts, we use the
+Except for the N+1 failures, offline instances counts, failure
+domain violation counts and desired locations count, we use the
 standard deviation since when used with values within a fixed range
 (we use percents expressed as values between zero and one) it gives
 consistent results across all metrics (there are some small issues
@@ -186,10 +188,10 @@ heuristic, instances from nodes with high CPU load will tend to move to
 nodes with less CPU load.
 
 On a perfectly balanced cluster (all nodes the same size, all
-instances the same size and spread across the nodes equally), the
-values for all metrics would be zero, with the exception of the total
-percentage of reserved memory. This doesn't happen too often in
-practice :)
+instances the same size and spread across the nodes equally,
+all desired locations satisfied), the values for all metrics
+would be zero, with the exception of the total percentage of
+reserved memory. This doesn't happen too often in practice :)
 
 OFFLINE INSTANCES
 ~~~~~~~~~~~~~~~~~
@@ -200,6 +202,21 @@ wrong calculations. For this reason, the algorithm subtracts the
 memory size of down instances from the free node memory of their
 primary node, in effect simulating the startup of such instances.
 
+DESIRED LOCATION TAGS
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes, administrators want specific instances located in a particular,
+typically geographic, location. To suppoer this desired location tags are
+introduced.
+
+If the cluster is tagged *htools:desiredlocation:x* then tags starting with
+*x* are desired location tags. Instances can be assigned tags of the form *x*
+that means that instance wants to be placed on a node tagged with a location
+tag *x*. (That means that cluster should be tagged *htools:nlocation:x* too).
+
+Instance pinning is just heuristics, not a hard enforced requirement;
+it will only be achieved by the cluster metrics favouring such placements.
+
 EXCLUSION TAGS
 ~~~~~~~~~~~~~~