code.grnet.gr Git - ganeti-local/blob - hn1.1

   1 .TH HN1 1 2009-03-14 htools "Ganeti H-tools"
   2 .SH NAME
   3 hn1 \- N+1 fixer for Ganeti
   4
   5 .SH SYNOPSIS
   6 .B hn1
   7 .B "[-C]"
   8 .B "[-p]"
   9 .B "[-o]"
  10 .BI "[ -m " cluster "]"
  11 .BI "[-n " nodes-file " ]"
  12 .BI "[ -i " instances-file "]"
  13 .BI "[-d " depth "]"
  14 .BI "[-r " max-removals "]"
  15 .BI "[-L " max-delta "]"
  16 .BI "[-l " min-delta "]"
  17
  18 .B hn1
  19 .B --version
  20
  21 .SH DESCRIPTION
  22 hn1 is a cluster N+1 fixer that tries to compute the minimum number of
  23 moves needed for getting all nodes to be N+1 compliant.
  24
  25 The algorithm is designed to be a 'perfect' algorithm, so that we
  26 always examine the entire solution space until we find the minimum
  27 solution. The algorithm can be tweaked via the \fB-d\fR, \fB-r\fR,
  28 \fB-L\fR and \fB-l\fR options.
  29
  30 By default, the program will show the solution in a somewhat cryptic
  31 format; for getting the actual Ganeti command list, use the \fB-C\fR
  32 option.
  33
  34 \fBNote:\fR this program is somewhat deprecated; \fBhbal(1)\fR gives
  35 usually much faster results, and a better cluster. It is recommended
  36 to use this program only when \fBhbal\fR doesn't give a N+1 compliant
  37 cluster.
  38
  39 .SS ALGORITHM
  40
  41 The algorithm works in multiple rounds, of increasing \fIdepth\fR,
  42 until we have a solution.
  43
  44 First, before starting the solution computation, we compute all the
  45 N+1-fail nodes and the instances they hold. These instances are
  46 candidate for replacement (and only these!).
  47
  48 The program start then with \fIdepth\fR one (unless overridden via the
  49 \fB-d\fR option), and at each round:
  50   - it tries to remove from the cluster as many instances as the
  51     current depth in order to make the cluster N+1 compliant
  52   - then, for each of the possible instance combinations that allow
  53     this (unless the total size is reduced via the \fB-r\fR option),
  54     it tries to put them back on the cluster while maintaining N+1
  55     compliance
  56
  57 It might be that at a given round, the results are:
  58   - no instance combination that can be put back; this means it is not
  59     possible to make the cluster N+1 compliant with this number of
  60     instances being moved, so we increase the depth and go on to the
  61     next round
  62   - one or more successful result, in which case we take the one that
  63     has as few changes as possible (by change meaning a replace-disks
  64     needed)
  65
  66 The main problem with the algorithm is that, being an exhaustive
  67 search, the CPU time required grows very very quickly based on
  68 depth. On a 20-node, 80-instances cluster, depths up to 5-6 are
  69 quickly computed, and depth 10 could already take days.
  70
  71 Since the algorithm is designed to prune the search space as quickly
  72 as possible, is by luck we find a good solution early at a given
  73 depth, then the other solutions which would result in a bigger delta
  74 (the number of changes) will not be investigated, and the program will
  75 finish fast. Since this is random and depends on where in the full
  76 solution space the good solution will be, there are two options for
  77 cutting down the time needed:
  78   - \fB-l\fR makes any solution that has delta lower than its
  79     parameter succeed instantly
  80   - \fB-L\fR makes any solution with delta higher than its parameter
  81     being rejected instantly (and not descend on the search tree)
  82
  83 .SH OPTIONS
  84 The options that can be passed to the program are as follows:
  85 .TP
  86 .B -C, --print-commands
  87 Print the command list at the end of the run. Without this, the
  88 program will only show a shorter, but cryptic output.
  89 .TP
  90 .B -p, --print-nodes
  91 Prints the before and after node status, in a format designed to allow
  92 the user to understand the node's most important parameters.
  93
  94 The node list will contain these informations:
  95   - a character denoting the N+1 status of the node, with blank
  96     meaning pass and an asterisk ('*') meaning fail
  97   - the node name
  98   - the total node memory
  99   - the free node memory
 100   - the reserved node memory, which is the amount of free memory
 101     needed for N+1 compliance
 102   - total disk
 103   - free disk
 104   - number of primary instances
 105   - number of secondary instances
 106   - percent of free memory
 107   - percent of free disk
 108
 109 .TP
 110 .BI "-n" nodefile ", --nodes=" nodefile
 111 The name of the file holding node information (if not collecting via
 112 RAPI), instead of the default
 113 .I nodes
 114 file.
 115
 116 .TP
 117 .BI "-i" instancefile ", --instances=" instancefile
 118 The name of the file holding instance information (if not collecting
 119 via RAPI), instead of the default
 120 .I instances
 121 file.
 122
 123 .TP
 124 .BI "-m" cluster
 125 Collect data not from files but directly from the
 126 .I cluster
 127 given as an argument via RAPI. This work for both Ganeti 1.2 and
 128 Ganeti 2.0.
 129
 130 .TP
 131 .BI "-d" DEPTH ", --depth=" DEPTH
 132 Start the algorithm directly at depth \fID\fR, so that we don't
 133 examine lower depth. This will be faster if we know a solution is not
 134 found a lower depths, and thus it's unneeded to search them.
 135
 136 .TP
 137 .BI "-l" MIN-DELTA ", --min-delta=" MIN-DELTA
 138 If we find a solution with delta lower or equal to \fIMIN-DELTA\fR,
 139 consider this a success and don't examine further.
 140
 141 .TP
 142 .BI "-L" MAX-DELTA ", --max-delta=" MAX-DELTA
 143 If while computing a solution, it's intermediate delta is already
 144 higher or equal to \fIMAX-DELTA\fR, consider this a failure and abort
 145 (as if N+1 checks have failed).
 146
 147 .TP
 148 .B -V, --version
 149 Just show the program version and exit.
 150
 151 .SH EXIT STATUS
 152
 153 The exist status of the command will be zero, unless for some reason
 154 the algorithm fatally failed (e.g. wrong node or instance data).
 155
 156 .SH BUGS
 157
 158 The program does not check its input data for consistency, and aborts
 159 with cryptic errors messages in this case.
 160
 161 The algorithm doesn't know when it won't be possible to reach N+1
 162 compliance at all, and will happily churn CPU for ages without
 163 realising it won't reach a solution.
 164
 165 The algorithm is too slow.
 166
 167 The output format is not easily scriptable, and the program should
 168 feed moves directly into Ganeti (either via RAPI or via a gnt-debug
 169 input file).
 170
 171 .SH SEE ALSO
 172 hbal(1), ganeti(7), gnt-instance(8), gnt-node(8)