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

   1 .TH HSPACE 1 2009-06-01 htools "Ganeti H-tools"
   2 .SH NAME
   3 hspace \- Cluster space analyzer for Ganeti
   4
   5 .SH SYNOPSIS
   6 .B hspace
   7 .B "[-p]"
   8 .B "[-v... | -q]"
   9 .BI "[-O" name... "]"
  10 .BI "[-m " cluster "]"
  11 .BI "[-n " nodes-file " ]"
  12 .BI "[-i " instances-file "]"
  13 .BI "[--memory " mem "]"
  14 .BI "[--disk " disk "]"
  15 .BI "[--req-nodes " req-nodes "]"
  16
  17 .B hspace
  18 .B --version
  19
  20 .SH DESCRIPTION
  21 hspace computes how many additional instances can be fit on a cluster,
  22 while maintaining N+1 status.
  23
  24 The program will try to place instances, all of the same size, on the
  25 cluster, until the point where we don't have any N+1 possible
  26 allocation. It uses the exact same allocation algorithm as the hail
  27 iallocator plugin.
  28
  29 With default options, the output of the program is designed to be
  30 parseable; when the -p option is passed, this is no longer true.
  31
  32 .SH OPTIONS
  33 The options that can be passed to the program are as follows:
  34
  35 .TP
  36 .BI "--memory " mem
  37 The memory size of the instances to be placed (defaults to 4GiB).
  38
  39 .TP
  40 .BI "--disk " disk
  41 The disk size of the instances to be placed (defaults to 100GiB).
  42
  43 .TP
  44 .BI "--req-nodes " num-nodes
  45 The number of nodes for the instances; the default of two means
  46 mirrored instances, while passing one means plain type instances.
  47
  48 .TP
  49 .B -p, --print-nodes
  50 Prints the before and after node status, in a format designed to allow
  51 the user to understand the node's most important parameters.
  52
  53 The node list will contain these informations:
  54 .RS
  55 .TP
  56 .B F
  57 a character denoting the status of the node, with '-' meaning an
  58 offline node, '*' meaning N+1 failure and blank meaning a good node
  59 .TP
  60 .B Name
  61 the node name
  62 .TP
  63 .B t_mem
  64 the total node memory
  65 .TP
  66 .B n_mem
  67 the memory used by the node itself
  68 .TP
  69 .B i_mem
  70 the memory used by instances
  71 .TP
  72 .B x_mem
  73 amount memory which seems to be in use but cannot be determined why or
  74 by which instance; usually this means that the hypervisor has some
  75 overhead or that there are other reporting errors
  76 .TP
  77 .B f_mem
  78 the free node memory
  79 .TP
  80 .B r_mem
  81 the reserved node memory, which is the amount of free memory needed
  82 for N+1 compliance
  83 .TP
  84 .B t_dsk
  85 total disk
  86 .TP
  87 .B f_dsk
  88 free disk
  89 .TP
  90 .B pri
  91 number of primary instances
  92 .TP
  93 .B sec
  94 number of secondary instances
  95 .TP
  96 .B p_fmem
  97 percent of free memory
  98 .TP
  99 .B p_fdsk
 100 percent of free disk
 101 .RE
 102
 103 .TP
 104 .BI "-O " name
 105 This option (which can be given multiple times) will mark nodes as
 106 being \fIoffline\fR, and instances won't be placed on these nodes.
 107
 108 Note that hspace will also mark as offline any nodes which are
 109 reported by RAPI as such, or that have "?" in file-based input in any
 110 numeric fields.
 111 .RE
 112
 113 .TP
 114 .BI "-n" nodefile ", --nodes=" nodefile
 115 The name of the file holding node information (if not collecting via
 116 RAPI), instead of the default \fInodes\fR file (but see below how to
 117 customize the default value via the environment).
 118
 119 .TP
 120 .BI "-i" instancefile ", --instances=" instancefile
 121 The name of the file holding instance information (if not collecting
 122 via RAPI), instead of the default \fIinstances\fR file (but see below
 123 how to customize the default value via the environment).
 124
 125 .TP
 126 .BI "-m" cluster
 127 Collect data not from files but directly from the
 128 .I cluster
 129 given as an argument via RAPI. If the argument doesn't contain a colon
 130 (:), then it is converted into a fully-built URL via prepending
 131 https:// and appending the default RAPI port, otherwise it's
 132 considered a fully-specified URL and is used as-is.
 133
 134 .TP
 135 .B -v, --verbose
 136 Increase the output verbosity. Each usage of this option will increase
 137 the verbosity (currently more than 2 doesn't make sense) from the
 138 default of one. At verbosity 2 the location of the new instances is
 139 shown in program output.
 140
 141 .TP
 142 .B -q, --quiet
 143 Decrease the output verbosity. Each usage of this option will decrease
 144 the verbosity (less than zero doesn't make sense) from the default of
 145 one.
 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 algorithm is highly dependent on the number of nodes; its runtime
 159 grows exponentially with this number, and as such is impractical for
 160 really big clusters.
 161
 162 The algorithm doesn't rebalance the cluster or try to get the optimal
 163 fit; it just allocates in the best place for the current step, without
 164 taking into consideration the impact on future placements.
 165
 166 .SH EXAMPLE
 167
 168 .SS Default output
 169
 170 .in +4n
 171 .nf
 172 .RB "$" " hspace --mem 16 --disk 16 --req-nodes 2"
 173 Initial score: 0.38988095
 174 Initial instances: 3
 175 Initial free RAM: 546
 176 Initial free disk: 260600
 177 Final score: 0.32638889
 178 Final instances: 7
 179 Final free RAM: 482
 180 Final free disk: 260472
 181 Usage: 0.43
 182 Allocations: 4
 183 .fi
 184 .in
 185
 186 This shows that (on this fake cluster), starting from 3 initial
 187 instances, using the hail iallocator plugin, it would be possible to
 188 add four (Allocations: 4) new instances to the cluster.
 189
 190 .SS Verbose output
 191
 192 For the same cluster as above:
 193 .in +4n
 194 .nf
 195 .RB "$" " hspace --mem 16 --disk 16 --req-nodes 2 -v"
 196 Initial score: 0.38988095
 197 Initial instances: 3
 198 Initial free RAM: 546
 199 Initial free disk: 260600
 200 Final score: 0.32638889
 201 Final instances: 7
 202 Final free RAM: 482
 203 Final free disk: 260472
 204 Usage: 0.43
 205 Allocations: 4
 206 Inst: new-0 node2 node1
 207 Inst: new-1 node2 node1
 208 Inst: new-2 node2 node1
 209 Inst: new-3 node2 node1
 210 .fi
 211 .in
 212
 213 The output now includes the placement for the new instances (named
 214 \fBnew-\fInumber\fR).
 215
 216 .SH ENVIRONMENT
 217
 218 If the variables \fBHTOOLS_NODES\fR and \fBHTOOLS_INSTANCES\fR are
 219 present in the environment, they will override the default names for
 220 the nodes and instances files. These will have of course no effect
 221 when RAPI is used.
 222
 223 .SH SEE ALSO
 224 .BR hbal "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), "
 225 .BR gnt-node "(8)"
 226
 227 .SH "COPYRIGHT"
 228 .PP
 229 Copyright (C) 2009 Google Inc. Permission is granted to copy,
 230 distribute and/or modify under the terms of the GNU General Public
 231 License as published by the Free Software Foundation; either version 2
 232 of the License, or (at your option) any later version.
 233 .PP
 234 On Debian systems, the complete text of the GNU General Public License
 235 can be found in /usr/share/common-licenses/GPL.