Merge branch 'stable-2.15' into stable-2.16
[ganeti-github.git] / man / hbal.rst
1 HBAL(1) Ganeti | Version @GANETI_VERSION@
2 =========================================
3
4 NAME
5 ----
6
7 hbal \- Cluster balancer for Ganeti
8
9 SYNOPSIS
10 --------
11
12 **hbal** {backend options...} [algorithm options...] [reporting options...]
13
14 **hbal** \--version
15
16
17 Backend options:
18
19 { **-m** *cluster* | **-L[** *path* **] [-X]** | **-t** *data-file* |
20 **-I** *path* }
21
22 Algorithm options:
23
24 **[ \--max-cpu *cpu-ratio* ]**
25 **[ \--min-disk *disk-ratio* ]**
26 **[ -l *limit* ]**
27 **[ -e *score* ]**
28 **[ -g *delta* ]** **[ \--min-gain-limit *threshold* ]**
29 **[ -O *name...* ]**
30 **[ \--no-disk-moves ]**
31 **[ \--no-instance-moves ]**
32 **[ -U *util-file* ]**
33 **[ \--ignore-dynu ]**
34 **[ \--ignore-soft-errors ]**
35 **[ \--mond *yes|no* ]**
36 **[ \--mond-xen ]**
37 **[ \--exit-on-missing-mond-data ]**
38 **[ \--evac-mode ]**
39 **[ \--restricted-migration ]**
40 **[ \--select-instances *inst...* ]**
41 **[ \--exclude-instances *inst...* ]**
42
43 Reporting options:
44
45 **[ -C[ *file* ] ]**
46 **[ -p[ *fields* ] ]**
47 **[ \--print-instances ]**
48 **[ -S *file* ]**
49 **[ -v... | -q ]**
50
51
52 DESCRIPTION
53 -----------
54
55 hbal is a cluster balancer that looks at the current state of the
56 cluster (nodes with their total and free disk, memory, etc.) and
57 instance placement and computes a series of steps designed to bring
58 the cluster into a better state.
59
60 The algorithm used is designed to be stable (i.e. it will give you the
61 same results when restarting it from the middle of the solution) and
62 reasonably fast. It is not, however, designed to be a perfect algorithm:
63 it is possible to make it go into a corner from which it can find no
64 improvement, because it looks only one "step" ahead.
65
66 The program accesses the cluster state via Rapi or Luxi. It also
67 requests data over the network from all MonDs with the --mond option.
68 Currently it uses only data produced by CPUload collector.
69
70 By default, the program will show the solution incrementally as it is
71 computed, in a somewhat cryptic format; for getting the actual Ganeti
72 command list, use the **-C** option.
73
74 ALGORITHM
75 ~~~~~~~~~
76
77 The program works in independent steps; at each step, we compute the
78 best instance move that lowers the cluster score.
79
80 The possible move type for an instance are combinations of
81 failover/migrate and replace-disks such that we change one of the
82 instance nodes, and the other one remains (but possibly with changed
83 role, e.g. from primary it becomes secondary). The list is:
84
85 - failover (f)
86 - replace secondary (r)
87 - replace primary, a composite move (f, r, f)
88 - failover and replace secondary, also composite (f, r)
89 - replace secondary and failover, also composite (r, f)
90
91 We don't do the only remaining possibility of replacing both nodes
92 (r,f,r,f or the equivalent f,r,f,r) since these move needs an
93 exhaustive search over both candidate primary and secondary nodes, and
94 is O(n*n) in the number of nodes. Furthermore, it doesn't seems to
95 give better scores but will result in more disk replacements.
96
97 PLACEMENT RESTRICTIONS
98 ~~~~~~~~~~~~~~~~~~~~~~
99
100 At each step, we prevent an instance move if it would cause:
101
102 - a node to go into N+1 failure state
103 - an instance to move onto an offline node (offline nodes are either
104   read from the cluster or declared with *-O*; drained nodes are
105   considered offline)
106 - an exclusion-tag based conflict (exclusion tags are read from the
107   cluster and/or defined via the *\--exclusion-tags* option)
108 - a max vcpu/pcpu ratio to be exceeded (configured via *\--max-cpu*)
109 - min disk free percentage to go below the configured limit
110   (configured via *\--min-disk*)
111
112 CLUSTER SCORING
113 ~~~~~~~~~~~~~~~
114
115 As said before, the algorithm tries to minimise the cluster score at
116 each step. Currently this score is computed as a weighted sum of the
117 following components:
118
119 - standard deviation of the percent of free memory
120 - standard deviation of the percent of reserved memory
121 - the sum of the percentages of reserved memory
122 - standard deviation of the percent of free disk
123 - count of nodes failing N+1 check
124 - count of instances living (either as primary or secondary) on
125   offline nodes; in the sense of hbal (and the other htools) drained
126   nodes are considered offline
127 - count of instances living (as primary) on offline nodes; this
128   differs from the above metric by helping failover of such instances
129   in 2-node clusters
130 - standard deviation of the ratio of virtual-to-physical cpus (for
131   primary instances of the node)
132 - standard deviation of the fraction of the available spindles
133   (in dedicated mode, spindles represent physical spindles; otherwise
134   this oversubscribable measure for IO load, and the oversubscription
135   factor is taken into account when computing the number of available
136   spindles)
137 - standard deviation of the dynamic load on the nodes, for cpus,
138   memory, disk and network
139 - standard deviation of the CPU load provided by MonD
140 - the count of instances with primary and secondary in the same failure
141   domain
142 - the count of instances sharing the same exclusion tags which primary
143   instances placed in the same failure domain
144 - the overall sum of dissatisfied desired locations among all cluster
145   instances
146
147 The free memory and free disk values help ensure that all nodes are
148 somewhat balanced in their resource usage. The reserved memory helps
149 to ensure that nodes are somewhat balanced in holding secondary
150 instances, and that no node keeps too much memory reserved for
151 N+1. And finally, the N+1 percentage helps guide the algorithm towards
152 eliminating N+1 failures, if possible.
153
154 Except for the N+1 failures, offline instances counts, failure
155 domain violation counts and desired locations count, we use the
156 standard deviation since when used with values within a fixed range
157 (we use percents expressed as values between zero and one) it gives
158 consistent results across all metrics (there are some small issues
159 related to different means, but it works generally well). The 'count'
160 type values will have higher score and thus will matter more for
161 balancing; thus these are better for hard constraints (like evacuating
162 nodes and fixing N+1 failures). For example, the offline instances
163 count (i.e. the number of instances living on offline nodes) will
164 cause the algorithm to actively move instances away from offline
165 nodes. This, coupled with the restriction on placement given by
166 offline nodes, will cause evacuation of such nodes.
167
168 The dynamic load values need to be read from an external file (Ganeti
169 doesn't supply them), and are computed for each node as: sum of
170 primary instance cpu load, sum of primary instance memory load, sum of
171 primary and secondary instance disk load (as DRBD generates write load
172 on secondary nodes too in normal case and in degraded scenarios also
173 read load), and sum of primary instance network load. An example of
174 how to generate these values for input to hbal would be to track ``xm
175 list`` for instances over a day and by computing the delta of the cpu
176 values, and feed that via the *-U* option for all instances (and keep
177 the other metrics as one). For the algorithm to work, all that is
178 needed is that the values are consistent for a metric across all
179 instances (e.g. all instances use cpu% to report cpu usage, and not
180 something related to number of CPU seconds used if the CPUs are
181 different), and that they are normalised to between zero and one. Note
182 that it's recommended to not have zero as the load value for any
183 instance metric since then secondary instances are not well balanced.
184
185 The CPUload from MonD's data collector will be used only if all MonDs
186 are running, otherwise it won't affect the cluster score. Since we can't
187 find the CPU load of each instance, we can assume that the CPU load of
188 an instance is proportional to the number of its vcpus. With this
189 heuristic, instances from nodes with high CPU load will tend to move to
190 nodes with less CPU load.
191
192 On a perfectly balanced cluster (all nodes the same size, all
193 instances the same size and spread across the nodes equally,
194 all desired locations satisfied), the values for all metrics
195 would be zero, with the exception of the total percentage of
196 reserved memory. This doesn't happen too often in practice :)
197
198 OFFLINE INSTANCES
199 ~~~~~~~~~~~~~~~~~
200
201 Since current Ganeti versions do not report the memory used by offline
202 (down) instances, ignoring the run status of instances will cause
203 wrong calculations. For this reason, the algorithm subtracts the
204 memory size of down instances from the free node memory of their
205 primary node, in effect simulating the startup of such instances.
206
207 DESIRED LOCATION TAGS
208 ~~~~~~~~~~~~~~~~~~~~~
209
210 Sometimes, administrators want specific instances located in a particular,
211 typically geographic, location. To suppoer this desired location tags are
212 introduced.
213
214 If the cluster is tagged *htools:desiredlocation:x* then tags starting with
215 *x* are desired location tags. Instances can be assigned tags of the form *x*
216 that means that instance wants to be placed on a node tagged with a location
217 tag *x*. (That means that cluster should be tagged *htools:nlocation:x* too).
218
219 Instance pinning is just heuristics, not a hard enforced requirement;
220 it will only be achieved by the cluster metrics favouring such placements.
221
222 EXCLUSION TAGS
223 ~~~~~~~~~~~~~~
224
225 The exclusion tags mechanism is designed to prevent instances which
226 run the same workload (e.g. two DNS servers) to land on the same node,
227 which would make the respective node a SPOF for the given service.
228
229 It works by tagging instances with certain tags and then building
230 exclusion maps based on these. Which tags are actually used is
231 configured either via the command line (option *\--exclusion-tags*)
232 or via adding them to the cluster tags:
233
234 \--exclusion-tags=a,b
235   This will make all instance tags of the form *a:\**, *b:\** be
236   considered for the exclusion map
237
238 cluster tags *htools:iextags:a*, *htools:iextags:b*
239   This will make instance tags *a:\**, *b:\** be considered for the
240   exclusion map. More precisely, the suffix of cluster tags starting
241   with *htools:iextags:* will become the prefix of the exclusion tags.
242
243 Both the above forms mean that two instances both having (e.g.) the
244 tag *a:foo* or *b:bar* won't end on the same node.
245
246 MIGRATION TAGS
247 ~~~~~~~~~~~~~~
248
249 If Ganeti is deployed on a heterogeneous cluster, migration might
250 not be possible between all nodes of a node group. One example of
251 such a situation is upgrading the hypervisor node by node. To make
252 hbal aware of those restrictions, the following cluster tags are used.
253
254 cluster tags *htools:migration:a*, *htools:migration:b*, etc
255   This make make node tags of the form *a:\**, *b:\**, etc be considered
256   migration restriction. More precisely, the suffix of cluster tags starting
257   with *htools:migration:* will become the prefix of the migration tags.
258   Only those migrations will be taken into consideration where all migration
259   tags of the source node are also present on the target node.
260
261 cluster tags *htools:allowmigration:x::y* for migration tags *x* and *y*
262   This asserts that a node taged *y* is able to receive instances in
263   the same way as if they had an *x* tag.
264
265 So in the simple case of a hypervisor upgrade, tagging all the nodes
266 that have been upgraded with a migration tag suffices. In more complicated
267 situations, it is always possible to use a different migration tag for
268 each hypervisor used and explictly state the allowed migration directions
269 by means of *htools:allowmigration:* tags.
270
271 LOCATION TAGS
272 ~~~~~~~~~~~~~
273
274 Within a node group, certain nodes might be more likely to fail simultaneously
275 due to a common cause of error (e.g., if they share the same power supply unit).
276 Ganeti can be made aware of thos common causes of failure by means of tags.
277
278 cluster tags *htools:nlocation:a*, *htools:nlocation:b*, etc
279   This make make node tags of the form *a:\**, *b:\**, etc be considered
280   to have a common cause of failure.
281
282 Instances with primary and secondary node having a common cause of failure and
283 instances sharing the same exclusion tag with primary nodes having a common
284 failure are considered badly placed. While such placements are always allowed,
285 they count heavily towards the cluster score.
286
287 OPTIONS
288 -------
289
290 The options that can be passed to the program are as follows:
291
292 -C, \--print-commands
293   Print the command list at the end of the run. Without this, the
294   program will only show a shorter, but cryptic output.
295
296   Note that the moves list will be split into independent steps,
297   called "jobsets", but only for visual inspection, not for actually
298   parallelisation. It is not possible to parallelise these directly
299   when executed via "gnt-instance" commands, since a compound command
300   (e.g. failover and replace-disks) must be executed
301   serially. Parallel execution is only possible when using the Luxi
302   backend and the *-L* option.
303
304   The algorithm for splitting the moves into jobsets is by
305   accumulating moves until the next move is touching nodes already
306   touched by the current moves; this means we can't execute in
307   parallel (due to resource allocation in Ganeti) and thus we start a
308   new jobset.
309
310 -p, \--print-nodes
311   Prints the before and after node status, in a format designed to allow
312   the user to understand the node's most important parameters. See the
313   man page **htools**\(1) for more details about this option.
314
315 \--print-instances
316   Prints the before and after instance map. This is less useful as the
317   node status, but it can help in understanding instance moves.
318
319 -O *name*
320   This option (which can be given multiple times) will mark nodes as
321   being *offline*. This means a couple of things:
322
323   - instances won't be placed on these nodes, not even temporarily;
324     e.g. the *replace primary* move is not available if the secondary
325     node is offline, since this move requires a failover.
326   - these nodes will not be included in the score calculation (except
327     for the percentage of instances on offline nodes)
328
329   Note that algorithm will also mark as offline any nodes which are
330   reported by RAPI as such, or that have "?" in file-based input in
331   any numeric fields.
332
333 -e *score*, \--min-score=*score*
334   This parameter denotes how much above the N+1 bound the cluster score
335   can for us to be happy with and alters the computation in two ways:
336
337   - if the cluster has the initial score lower than this value, then we
338     don't enter the algorithm at all, and exit with success
339   - during the iterative process, if we reach a score lower than this
340     value, we exit the algorithm
341
342   The default value of the parameter is currently ``1e-9`` (chosen
343   empirically).
344
345 -g *delta*, \--min-gain=*delta*
346   Since the balancing algorithm can sometimes result in just very tiny
347   improvements, that bring less gain that they cost in relocation
348   time, this parameter (defaulting to 0.01) represents the minimum
349   gain we require during a step, to continue balancing.
350
351 \--min-gain-limit=*threshold*
352   The above min-gain option will only take effect if the cluster score
353   is already below *threshold* (defaults to 0.1). The rationale behind
354   this setting is that at high cluster scores (badly balanced
355   clusters), we don't want to abort the rebalance too quickly, as
356   later gains might still be significant. However, under the
357   threshold, the total gain is only the threshold value, so we can
358   exit early.
359
360 \--no-disk-moves
361   This parameter prevents hbal from using disk move
362   (i.e. "gnt-instance replace-disks") operations. This will result in
363   a much quicker balancing, but of course the improvements are
364   limited. It is up to the user to decide when to use one or another.
365
366 \--no-instance-moves
367   This parameter prevents hbal from using instance moves
368   (i.e. "gnt-instance migrate/failover") operations. This will only use
369   the slow disk-replacement operations, and will also provide a worse
370   balance, but can be useful if moving instances around is deemed unsafe
371   or not preferred.
372
373 \--evac-mode
374   This parameter restricts the list of instances considered for moving
375   to the ones living on offline/drained nodes. It can be used as a
376   (bulk) replacement for Ganeti's own *gnt-node evacuate*, with the
377   note that it doesn't guarantee full evacuation.
378
379 \--restricted-migration
380   This parameter disallows any replace-primary moves (frf), as well as
381   those replace-and-failover moves (rf) where the primary node of the
382   instance is not drained. If used together with the ``--evac-mode``
383   option, the only migrations that hbal will do are migrations of
384   instances off a drained node. This can be useful if during a reinstall
385   of the base operating system migration is only possible from the old
386   OS to the new OS. Note, however, that usually the use of migration
387   tags is the better choice.
388
389 \--select-instances=*instances*
390   This parameter marks the given instances (as a comma-separated list)
391   as the only ones being moved during the rebalance.
392
393 \--exclude-instances=*instances*
394   This parameter marks the given instances (as a comma-separated list)
395   from being moved during the rebalance.
396
397 -U *util-file*
398   This parameter specifies a file holding instance dynamic utilisation
399   information that will be used to tweak the balancing algorithm to
400   equalise load on the nodes (as opposed to static resource
401   usage). The file is in the format "instance_name cpu_util mem_util
402   disk_util net_util" where the "_util" parameters are interpreted as
403   numbers and the instance name must match exactly the instance as
404   read from Ganeti. In case of unknown instance names, the program
405   will abort.
406
407   If not given, the default values are one for all metrics and thus
408   dynamic utilisation has only one effect on the algorithm: the
409   equalisation of the secondary instances across nodes (this is the
410   only metric that is not tracked by another, dedicated value, and
411   thus the disk load of instances will cause secondary instance
412   equalisation). Note that value of one will also influence slightly
413   the primary instance count, but that is already tracked via other
414   metrics and thus the influence of the dynamic utilisation will be
415   practically insignificant.
416
417 \--ignore-dynu
418   If given, all dynamic utilisation information will be ignored by
419   assuming it to be 0. This option will take precedence over any data
420   passed by the ``-U`` option or by the MonDs with the ``--mond`` and
421   the ``--mond-data`` option.
422
423 \--ignore-soft-errors
424   If given, all checks for soft errors will be ommitted when considering
425   balancing moves. In this way, progress can be made in a cluster where
426   all nodes are in a policy-wise bad state, like exceeding oversubscription
427   ratios on CPU or spindles.
428
429 -S *filename*, \--save-cluster=*filename*
430   If given, the state of the cluster before the balancing is saved to
431   the given file plus the extension "original"
432   (i.e. *filename*.original), and the state at the end of the
433   balancing is saved to the given file plus the extension "balanced"
434   (i.e. *filename*.balanced). This allows re-feeding the cluster state
435   to either hbal itself or for example hspace via the ``-t`` option.
436
437 -t *datafile*, \--text-data=*datafile*
438   Backend specification: the name of the file holding node and instance
439   information (if not collecting via RAPI or LUXI). This or one of the
440   other backends must be selected. The option is described in the man
441   page **htools**\(1).
442
443 \--mond=*yes|no*
444   If given the program will query all MonDs to fetch data from the
445   supported data collectors over the network.
446
447 \--mond-xen
448   If given, also query Xen-specific collectors from MonD, provided
449   that monitoring daemons are queried at all.
450
451 \--exit-on-missing-mond-data
452   If given, abort if the data obtainable from querying MonDs is incomplete.
453   The default behavior is to continue with a best guess based on the static
454   information.
455
456 \--mond-data *datafile*
457   The name of the file holding the data provided by MonD, to override
458   quering MonDs over the network. This is mostly used for debugging. The
459   file must be in JSON format and present an array of JSON objects ,
460   one for every node, with two members. The first member named ``node``
461   is the name of the node and the second member named ``reports`` is an
462   array of report objects. The report objects must be in the same format
463   as produced by the monitoring agent.
464
465 -m *cluster*
466   Backend specification: collect data directly from the *cluster* given
467   as an argument via RAPI. The option is described in the man page
468   **htools**\(1).
469
470 -L [*path*]
471   Backend specification: collect data directly from the master daemon,
472   which is to be contacted via LUXI (an internal Ganeti protocol). The
473   option is described in the man page **htools**\(1).
474
475 -X
476   When using the Luxi backend, hbal can also execute the given
477   commands. The execution method is to execute the individual jobsets
478   (see the *-C* option for details) in separate stages, aborting if at
479   any time a jobset doesn't have all jobs successful. Each step in the
480   balancing solution will be translated into exactly one Ganeti job
481   (having between one and three OpCodes), and all the steps in a
482   jobset will be executed in parallel. The jobsets themselves are
483   executed serially.
484
485   The execution of the job series can be interrupted, see below for
486   signal handling.
487
488 -l *N*, \--max-length=*N*
489   Restrict the solution to this length. This can be used for example
490   to automate the execution of the balancing.
491
492 \--max-cpu=*cpu-ratio*
493   The maximum virtual to physical cpu ratio, as a floating point number
494   greater than or equal to one. For example, specifying *cpu-ratio* as
495   **2.5** means that, for a 4-cpu machine, a maximum of 10 virtual cpus
496   should be allowed to be in use for primary instances. A value of
497   exactly one means there will be no over-subscription of CPU (except
498   for the CPU time used by the node itself), and values below one do not
499   make sense, as that means other resources (e.g. disk) won't be fully
500   utilised due to CPU restrictions.
501
502 \--min-disk=*disk-ratio*
503   The minimum amount of free disk space remaining, as a floating point
504   number. For example, specifying *disk-ratio* as **0.25** means that
505   at least one quarter of disk space should be left free on nodes.
506
507 -G *uuid*, \--group=*uuid*
508   On an multi-group cluster, select this group for
509   processing. Otherwise hbal will abort, since it cannot balance
510   multiple groups at the same time.
511
512 -v, \--verbose
513   Increase the output verbosity. Each usage of this option will
514   increase the verbosity (currently more than 2 doesn't make sense)
515   from the default of one.
516
517 -q, \--quiet
518   Decrease the output verbosity. Each usage of this option will
519   decrease the verbosity (less than zero doesn't make sense) from the
520   default of one.
521
522 -V, \--version
523   Just show the program version and exit.
524
525 SIGNAL HANDLING
526 ---------------
527
528 When executing jobs via LUXI (using the ``-X`` option), normally hbal
529 will execute all jobs until either one errors out or all the jobs finish
530 successfully.
531
532 Since balancing can take a long time, it is possible to stop hbal early
533 in two ways:
534
535 - by sending a ``SIGINT`` (``^C``), hbal will register the termination
536   request, and will wait until the currently submitted jobs finish, at
537   which point it will exit (with exit code 0 if all jobs finished
538   correctly, otherwise with exit code 1 as usual)
539
540 - by sending a ``SIGTERM``, hbal will immediately exit (with exit code
541   2\); it is the responsibility of the user to follow up with Ganeti
542   and check the result of the currently-executing jobs
543
544 Note that in any situation, it's perfectly safe to kill hbal, either via
545 the above signals or via any other signal (e.g. ``SIGQUIT``,
546 ``SIGKILL``), since the jobs themselves are processed by Ganeti whereas
547 hbal (after submission) only watches their progression. In this case,
548 the user will have to query Ganeti for job results.
549
550 EXIT STATUS
551 -----------
552
553 The exit status of the command will be zero, unless for some reason the
554 algorithm failed (e.g. wrong node or instance data), invalid command
555 line options, or (in case of job execution) one of the jobs has failed.
556
557 Once job execution via Luxi has started (``-X``), if the balancing was
558 interrupted early (via *SIGINT*, or via ``--max-length``) but all jobs
559 executed successfully, then the exit status is zero; a non-zero exit
560 code means that the cluster state should be investigated, since a job
561 failed or we couldn't compute its status and this can also point to a
562 problem on the Ganeti side.
563
564 BUGS
565 ----
566
567 The program does not check all its input data for consistency, and
568 sometime aborts with cryptic errors messages with invalid data.
569
570 The algorithm is not perfect.
571
572 EXAMPLE
573 -------
574
575 Note that these examples are not for the latest version (they don't
576 have full node data).
577
578 Default output
579 ~~~~~~~~~~~~~~
580
581 With the default options, the program shows each individual step and
582 the improvements it brings in cluster score::
583
584     $ hbal
585     Loaded 20 nodes, 80 instances
586     Cluster is not N+1 happy, continuing but no guarantee that the cluster will end N+1 happy.
587     Initial score: 0.52329131
588     Trying to minimize the CV...
589         1. instance14  node1:node10  => node16:node10 0.42109120 a=f r:node16 f
590         2. instance54  node4:node15  => node16:node15 0.31904594 a=f r:node16 f
591         3. instance4   node5:node2   => node2:node16  0.26611015 a=f r:node16
592         4. instance48  node18:node20 => node2:node18  0.21361717 a=r:node2 f
593         5. instance93  node19:node18 => node16:node19 0.16166425 a=r:node16 f
594         6. instance89  node3:node20  => node2:node3   0.11005629 a=r:node2 f
595         7. instance5   node6:node2   => node16:node6  0.05841589 a=r:node16 f
596         8. instance94  node7:node20  => node20:node16 0.00658759 a=f r:node16
597         9. instance44  node20:node2  => node2:node15  0.00438740 a=f r:node15
598        10. instance62  node14:node18 => node14:node16 0.00390087 a=r:node16
599        11. instance13  node11:node14 => node11:node16 0.00361787 a=r:node16
600        12. instance19  node10:node11 => node10:node7  0.00336636 a=r:node7
601        13. instance43  node12:node13 => node12:node1  0.00305681 a=r:node1
602        14. instance1   node1:node2   => node1:node4   0.00263124 a=r:node4
603        15. instance58  node19:node20 => node19:node17 0.00252594 a=r:node17
604     Cluster score improved from 0.52329131 to 0.00252594
605
606 In the above output, we can see:
607
608 - the input data (here from files) shows a cluster with 20 nodes and
609   80 instances
610 - the cluster is not initially N+1 compliant
611 - the initial score is 0.52329131
612
613 The step list follows, showing the instance, its initial
614 primary/secondary nodes, the new primary secondary, the cluster list,
615 and the actions taken in this step (with 'f' denoting failover/migrate
616 and 'r' denoting replace secondary).
617
618 Finally, the program shows the improvement in cluster score.
619
620 A more detailed output is obtained via the *-C* and *-p* options::
621
622     $ hbal
623     Loaded 20 nodes, 80 instances
624     Cluster is not N+1 happy, continuing but no guarantee that the cluster will end N+1 happy.
625     Initial cluster status:
626     N1 Name   t_mem f_mem r_mem t_dsk f_dsk pri sec  p_fmem  p_fdsk
627      * node1  32762  1280  6000  1861  1026   5   3 0.03907 0.55179
628        node2  32762 31280 12000  1861  1026   0   8 0.95476 0.55179
629      * node3  32762  1280  6000  1861  1026   5   3 0.03907 0.55179
630      * node4  32762  1280  6000  1861  1026   5   3 0.03907 0.55179
631      * node5  32762  1280  6000  1861   978   5   5 0.03907 0.52573
632      * node6  32762  1280  6000  1861  1026   5   3 0.03907 0.55179
633      * node7  32762  1280  6000  1861  1026   5   3 0.03907 0.55179
634        node8  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
635        node9  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
636      * node10 32762  7280 12000  1861  1026   4   4 0.22221 0.55179
637        node11 32762  7280  6000  1861   922   4   5 0.22221 0.49577
638        node12 32762  7280  6000  1861  1026   4   4 0.22221 0.55179
639        node13 32762  7280  6000  1861   922   4   5 0.22221 0.49577
640        node14 32762  7280  6000  1861   922   4   5 0.22221 0.49577
641      * node15 32762  7280 12000  1861  1131   4   3 0.22221 0.60782
642        node16 32762 31280     0  1861  1860   0   0 0.95476 1.00000
643        node17 32762  7280  6000  1861  1106   5   3 0.22221 0.59479
644      * node18 32762  1280  6000  1396   561   5   3 0.03907 0.40239
645      * node19 32762  1280  6000  1861  1026   5   3 0.03907 0.55179
646        node20 32762 13280 12000  1861   689   3   9 0.40535 0.37068
647
648     Initial score: 0.52329131
649     Trying to minimize the CV...
650         1. instance14  node1:node10  => node16:node10 0.42109120 a=f r:node16 f
651         2. instance54  node4:node15  => node16:node15 0.31904594 a=f r:node16 f
652         3. instance4   node5:node2   => node2:node16  0.26611015 a=f r:node16
653         4. instance48  node18:node20 => node2:node18  0.21361717 a=r:node2 f
654         5. instance93  node19:node18 => node16:node19 0.16166425 a=r:node16 f
655         6. instance89  node3:node20  => node2:node3   0.11005629 a=r:node2 f
656         7. instance5   node6:node2   => node16:node6  0.05841589 a=r:node16 f
657         8. instance94  node7:node20  => node20:node16 0.00658759 a=f r:node16
658         9. instance44  node20:node2  => node2:node15  0.00438740 a=f r:node15
659        10. instance62  node14:node18 => node14:node16 0.00390087 a=r:node16
660        11. instance13  node11:node14 => node11:node16 0.00361787 a=r:node16
661        12. instance19  node10:node11 => node10:node7  0.00336636 a=r:node7
662        13. instance43  node12:node13 => node12:node1  0.00305681 a=r:node1
663        14. instance1   node1:node2   => node1:node4   0.00263124 a=r:node4
664        15. instance58  node19:node20 => node19:node17 0.00252594 a=r:node17
665     Cluster score improved from 0.52329131 to 0.00252594
666
667     Commands to run to reach the above solution:
668       echo step 1
669       echo gnt-instance migrate instance14
670       echo gnt-instance replace-disks -n node16 instance14
671       echo gnt-instance migrate instance14
672       echo step 2
673       echo gnt-instance migrate instance54
674       echo gnt-instance replace-disks -n node16 instance54
675       echo gnt-instance migrate instance54
676       echo step 3
677       echo gnt-instance migrate instance4
678       echo gnt-instance replace-disks -n node16 instance4
679       echo step 4
680       echo gnt-instance replace-disks -n node2 instance48
681       echo gnt-instance migrate instance48
682       echo step 5
683       echo gnt-instance replace-disks -n node16 instance93
684       echo gnt-instance migrate instance93
685       echo step 6
686       echo gnt-instance replace-disks -n node2 instance89
687       echo gnt-instance migrate instance89
688       echo step 7
689       echo gnt-instance replace-disks -n node16 instance5
690       echo gnt-instance migrate instance5
691       echo step 8
692       echo gnt-instance migrate instance94
693       echo gnt-instance replace-disks -n node16 instance94
694       echo step 9
695       echo gnt-instance migrate instance44
696       echo gnt-instance replace-disks -n node15 instance44
697       echo step 10
698       echo gnt-instance replace-disks -n node16 instance62
699       echo step 11
700       echo gnt-instance replace-disks -n node16 instance13
701       echo step 12
702       echo gnt-instance replace-disks -n node7 instance19
703       echo step 13
704       echo gnt-instance replace-disks -n node1 instance43
705       echo step 14
706       echo gnt-instance replace-disks -n node4 instance1
707       echo step 15
708       echo gnt-instance replace-disks -n node17 instance58
709
710     Final cluster status:
711     N1 Name   t_mem f_mem r_mem t_dsk f_dsk pri sec  p_fmem  p_fdsk
712        node1  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
713        node2  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
714        node3  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
715        node4  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
716        node5  32762  7280  6000  1861  1078   4   5 0.22221 0.57947
717        node6  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
718        node7  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
719        node8  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
720        node9  32762  7280  6000  1861  1026   4   4 0.22221 0.55179
721        node10 32762  7280  6000  1861  1026   4   4 0.22221 0.55179
722        node11 32762  7280  6000  1861  1022   4   4 0.22221 0.54951
723        node12 32762  7280  6000  1861  1026   4   4 0.22221 0.55179
724        node13 32762  7280  6000  1861  1022   4   4 0.22221 0.54951
725        node14 32762  7280  6000  1861  1022   4   4 0.22221 0.54951
726        node15 32762  7280  6000  1861  1031   4   4 0.22221 0.55408
727        node16 32762  7280  6000  1861  1060   4   4 0.22221 0.57007
728        node17 32762  7280  6000  1861  1006   5   4 0.22221 0.54105
729        node18 32762  7280  6000  1396   761   4   2 0.22221 0.54570
730        node19 32762  7280  6000  1861  1026   4   4 0.22221 0.55179
731        node20 32762 13280  6000  1861  1089   3   5 0.40535 0.58565
732
733 Here we see, beside the step list, the initial and final cluster
734 status, with the final one showing all nodes being N+1 compliant, and
735 the command list to reach the final solution. In the initial listing,
736 we see which nodes are not N+1 compliant.
737
738 The algorithm is stable as long as each step above is fully completed,
739 e.g. in step 8, both the migrate and the replace-disks are
740 done. Otherwise, if only the migrate is done, the input data is
741 changed in a way that the program will output a different solution
742 list (but hopefully will end in the same state).
743
744 .. vim: set textwidth=72 :
745 .. Local Variables:
746 .. mode: rst
747 .. fill-column: 72
748 .. End: