1 .TH HSPACE 1 2009-06-01 htools "Ganeti H-tools"
3 hspace \- Cluster space analyzer for Ganeti
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 .BI "[--max-cpu " cpu-ratio "]"
17 .BI "[--min-disk " disk-ratio "]"
23 hspace computes how many additional instances can be fit on a cluster,
24 while maintaining N+1 status.
26 The program will try to place instances, all of the same size, on the
27 cluster, until the point where we don't have any N+1 possible
28 allocation. It uses the exact same allocation algorithm as the hail
31 With default options, the output of the program is designed to be
32 parseable; when the -p option is passed, this is no longer true.
35 The options that can be passed to the program are as follows:
39 The memory size of the instances to be placed (defaults to 4GiB).
43 The disk size of the instances to be placed (defaults to 100GiB).
46 .BI "--req-nodes " num-nodes
47 The number of nodes for the instances; the default of two means
48 mirrored instances, while passing one means plain type instances.
51 .BI "--max-cpu " cpu-ratio
52 The maximum virtual-to-physical cpu ratio, as a floating point number
53 between zero and one. For example, specifying \fIcpu-ratio\fR as
54 \fB2.5\fR means that, for a 4-cpu machine, a maximum of 10 virtual
55 cpus should be allowed to be in use for primary instances. A value of
56 one doesn't make sense though, as that means no disk space can be used
60 .BI "--min-disk " disk-ratio
61 The minimum amount of free disk space remaining, as a floating point
62 number. For example, specifying \fIdisk-ratio\fR as \fB0.25\fR means
63 that at least one quarter of disk space should be left free on nodes.
67 Prints the before and after node status, in a format designed to allow
68 the user to understand the node's most important parameters.
70 The node list will contain these informations:
74 a character denoting the status of the node, with '-' meaning an
75 offline node, '*' meaning N+1 failure and blank meaning a good node
84 the memory used by the node itself
87 the memory used by instances
90 amount memory which seems to be in use but cannot be determined why or
91 by which instance; usually this means that the hypervisor has some
92 overhead or that there are other reporting errors
98 the reserved node memory, which is the amount of free memory needed
108 the number of physical cpus on the node
111 the number of virtual cpus allocated to primary instances
114 number of primary instances
117 number of secondary instances
120 percent of free memory
126 ratio of virtual to physical cpus
131 This option (which can be given multiple times) will mark nodes as
132 being \fIoffline\fR, and instances won't be placed on these nodes.
134 Note that hspace will also mark as offline any nodes which are
135 reported by RAPI as such, or that have "?" in file-based input in any
140 .BI "-n" nodefile ", --nodes=" nodefile
141 The name of the file holding node information (if not collecting via
142 RAPI), instead of the default \fInodes\fR file (but see below how to
143 customize the default value via the environment).
146 .BI "-i" instancefile ", --instances=" instancefile
147 The name of the file holding instance information (if not collecting
148 via RAPI), instead of the default \fIinstances\fR file (but see below
149 how to customize the default value via the environment).
153 Collect data not from files but directly from the
155 given as an argument via RAPI. If the argument doesn't contain a colon
156 (:), then it is converted into a fully-built URL via prepending
157 https:// and appending the default RAPI port, otherwise it's
158 considered a fully-specified URL and is used as-is.
162 Increase the output verbosity. Each usage of this option will increase
163 the verbosity (currently more than 2 doesn't make sense) from the
164 default of one. At verbosity 2 the location of the new instances is
165 shown in program output.
169 Decrease the output verbosity. Each usage of this option will decrease
170 the verbosity (less than zero doesn't make sense) from the default of
175 Just show the program version and exit.
179 The exist status of the command will be zero, unless for some reason
180 the algorithm fatally failed (e.g. wrong node or instance data).
184 The algorithm is highly dependent on the number of nodes; its runtime
185 grows exponentially with this number, and as such is impractical for
188 The algorithm doesn't rebalance the cluster or try to get the optimal
189 fit; it just allocates in the best place for the current step, without
190 taking into consideration the impact on future placements.
198 .RB "$" " hspace --mem 16 --disk 16 --req-nodes 2"
199 Initial score: 0.38988095
201 Initial free RAM: 546
202 Initial free disk: 260600
203 Final score: 0.32638889
206 Final free disk: 260472
212 This shows that (on this fake cluster), starting from 3 initial
213 instances, using the hail iallocator plugin, it would be possible to
214 add four (Allocations: 4) new instances to the cluster.
218 For the same cluster as above:
221 .RB "$" " hspace --mem 16 --disk 16 --req-nodes 2 -v"
222 Initial score: 0.38988095
224 Initial free RAM: 546
225 Initial free disk: 260600
226 Final score: 0.32638889
229 Final free disk: 260472
232 Inst: new-0 node2 node1
233 Inst: new-1 node2 node1
234 Inst: new-2 node2 node1
235 Inst: new-3 node2 node1
239 The output now includes the placement for the new instances (named
240 \fBnew-\fInumber\fR).
244 If the variables \fBHTOOLS_NODES\fR and \fBHTOOLS_INSTANCES\fR are
245 present in the environment, they will override the default names for
246 the nodes and instances files. These will have of course no effect
250 .BR hbal "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), "
255 Copyright (C) 2009 Google Inc. Permission is granted to copy,
256 distribute and/or modify under the terms of the GNU General Public
257 License as published by the Free Software Foundation; either version 2
258 of the License, or (at your option) any later version.
260 On Debian systems, the complete text of the GNU General Public License
261 can be found in /usr/share/common-licenses/GPL.