root / hspace.1 @ bd2f1465
History | View | Annotate | Download (10 kB)
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 "[backend options...]" |
8 |
.B "[algorithm options...]" |
9 |
.B "[request options..."] |
10 |
.B "[-p]" |
11 |
.B "[-v... | -q]" |
12 |
|
13 |
.B hspace |
14 |
.B --version |
15 |
|
16 |
.TP |
17 |
Backend options: |
18 |
.BI "[ -m " cluster " ]" |
19 |
| |
20 |
.BI "[ -L[" path "]]" |
21 |
| |
22 |
.BI "[ -n " nodes-file " ]" |
23 |
.BI "[ -i " instances-file " ]" |
24 |
|
25 |
.TP |
26 |
Algorithm options: |
27 |
.BI "[ --max-cpu " cpu-ratio " ]" |
28 |
.BI "[ --min-disk " disk-ratio " ]" |
29 |
.BI "[ -O " name... " ]" |
30 |
|
31 |
.TP |
32 |
Request options: |
33 |
.BI "[--memory " mem "]" |
34 |
.BI "[--disk " disk "]" |
35 |
.BI "[--req-nodes " req-nodes "]" |
36 |
.BI "[--vcpus " vcpus "]" |
37 |
|
38 |
|
39 |
.SH DESCRIPTION |
40 |
hspace computes how many additional instances can be fit on a cluster, |
41 |
while maintaining N+1 status. |
42 |
|
43 |
The program will try to place instances, all of the same size, on the |
44 |
cluster, until the point where we don't have any N+1 possible |
45 |
allocation. It uses the exact same allocation algorithm as the hail |
46 |
iallocator plugin. |
47 |
|
48 |
The output of the program is designed to interpreted as a shell |
49 |
fragment (or parsed as a \fIkey=value\fR file). Options which extend |
50 |
the output (e.g. -p, -v) will output the additional information on |
51 |
stderr (such that the stdout is still parseable). |
52 |
|
53 |
The following keys are available in the output of the script (all |
54 |
prefixed with \fIHTS_\fR): |
55 |
.TP |
56 |
.I SPEC_MEM, SPEC_DSK, SPEC_CPU, SPEC_RQN |
57 |
These represent the specifications of the instance model used for |
58 |
allocation (the memory, disk, cpu, requested nodes). |
59 |
|
60 |
.TP |
61 |
.I CLUSTER_MEM, CLUSTER_DSK, CLUSTER_CPU, CLUSTER_NODES |
62 |
These represent the total memory, disk, CPU count and total nodes in |
63 |
the cluster. |
64 |
|
65 |
.TP |
66 |
.I INI_SCORE, FIN_SCORE |
67 |
These are the initial (current) and final cluster score (see the hbal |
68 |
man page for details about the scoring algorithm). |
69 |
|
70 |
.TP |
71 |
.I INI_INST_CNT, FIN_INST_CNT |
72 |
The initial and final instance count. |
73 |
|
74 |
.TP |
75 |
.I INI_MEM_FREE, FIN_MEM_FREE |
76 |
The initial and final total free memory in the cluster (but this |
77 |
doesn't necessarily mean available for use). |
78 |
|
79 |
.TP |
80 |
.I INI_MEM_AVAIL, FIN_MEM_AVAIL |
81 |
The initial and final total available memory for allocation in the |
82 |
cluster. If allocating redundant instances, new instances could |
83 |
increase the reserved memory so it doesn't necessarily mean the |
84 |
entirety of this memory can be used for new instance allocations. |
85 |
|
86 |
.TP |
87 |
.I INI_MEM_RESVD, FIN_MEM_RESVD |
88 |
The initial and final reserved memory (for redundancy/N+1 purposes). |
89 |
|
90 |
.TP |
91 |
.I INI_MEM_INST, FIN_MEM_INST |
92 |
The initial and final memory used for instances (actual runtime used |
93 |
RAM). |
94 |
|
95 |
.TP |
96 |
.I INI_MEM_OVERHEAD, FIN_MEM_OVERHEAD |
97 |
The initial and final memory overhead - memory used for the node |
98 |
itself and unacounted memory (e.g. due to hypervisor overhead). |
99 |
|
100 |
.TP |
101 |
.I INI_MEM_EFF, HTS_INI_MEM_EFF |
102 |
The initial and final memory efficiency, represented as instance |
103 |
memory divided by total memory. |
104 |
|
105 |
.TP |
106 |
.I INI_DSK_FREE, INI_DSK_AVAIL, INI_DSK_RESVD, INI_DSK_INST, INI_DSK_EFF |
107 |
Initial disk stats, similar to the memory ones. |
108 |
|
109 |
.TP |
110 |
.I FIN_DSK_FREE, FIN_DSK_AVAIL, FIN_DSK_RESVD, FIN_DSK_INST, FIN_DSK_EFF |
111 |
Final disk stats, similar to the memory ones. |
112 |
|
113 |
.TP |
114 |
.I INI_CPU_INST, FIN_CPU_INST |
115 |
Initial and final number of virtual CPUs used by instances. |
116 |
|
117 |
.TP |
118 |
.I INI_CPU_EFF, FIN_CPU_EFF |
119 |
The initial and final CPU efficiency, represented as the count of |
120 |
virtual instance CPUs divided by the total physical CPU count. |
121 |
|
122 |
.TP |
123 |
.I INI_MNODE_MEM_AVAIL, FIN_MNODE_MEM_AVAIL |
124 |
The initial and final maximum per-node available memory. This is not |
125 |
very useful as a metric but can give an impression of the status of |
126 |
the nodes; as an example, this value restricts the maximum instance |
127 |
size that can be still created on the cluster. |
128 |
|
129 |
.TP |
130 |
.I INI_MNODE_DSK_AVAIL, FIN_MNODE_DSK_AVAIL |
131 |
Like the above but for disk. |
132 |
|
133 |
.TP |
134 |
.I ALLOC_USAGE |
135 |
The current usage represented as initial number of instances divided |
136 |
per final number of instances. |
137 |
|
138 |
.TP |
139 |
.I ALLOC_COUNT |
140 |
The number of instances allocated (delta between FIN_INST_CNT and |
141 |
INI_INST_CNT). |
142 |
|
143 |
.TP |
144 |
.I ALLOC_FAIL*_CNT |
145 |
For the last attemp at allocations (which would have increased |
146 |
FIN_INST_CNT with one, if it had succeeded), this is the count of the |
147 |
failure reasons per failure type; currently defined are FAILMEM, |
148 |
FAILDISK and FAILCPU which represent errors due to not enough memory, |
149 |
disk and CPUs, and FAILN1 which represents a non N+1 compliant cluster |
150 |
on which we can't allocate instances at all. |
151 |
|
152 |
.TP |
153 |
.I ALLOC_FAIL_REASON |
154 |
The reason for most of the failures, being one of the above FAIL* |
155 |
strings. |
156 |
|
157 |
.TP |
158 |
.I OK |
159 |
A marker representing the successful end of the computation, and |
160 |
having value "1". If this key is not present in the output it means |
161 |
that the computation failed and any values present should not be |
162 |
relied upon. |
163 |
|
164 |
.SH OPTIONS |
165 |
The options that can be passed to the program are as follows: |
166 |
|
167 |
.TP |
168 |
.BI "--memory " mem |
169 |
The memory size of the instances to be placed (defaults to 4GiB). |
170 |
|
171 |
.TP |
172 |
.BI "--disk " disk |
173 |
The disk size of the instances to be placed (defaults to 100GiB). |
174 |
|
175 |
.TP |
176 |
.BI "--req-nodes " num-nodes |
177 |
The number of nodes for the instances; the default of two means |
178 |
mirrored instances, while passing one means plain type instances. |
179 |
|
180 |
.TP |
181 |
.BI "--vcpus " vcpus |
182 |
The number of VCPUs of the instances to be placed (defaults to 1). |
183 |
|
184 |
.TP |
185 |
.BI "--max-cpu " cpu-ratio |
186 |
The maximum virtual-to-physical cpu ratio, as a floating point number |
187 |
between zero and one. For example, specifying \fIcpu-ratio\fR as |
188 |
\fB2.5\fR means that, for a 4-cpu machine, a maximum of 10 virtual |
189 |
cpus should be allowed to be in use for primary instances. A value of |
190 |
one doesn't make sense though, as that means no disk space can be used |
191 |
on it. |
192 |
|
193 |
.TP |
194 |
.BI "--min-disk " disk-ratio |
195 |
The minimum amount of free disk space remaining, as a floating point |
196 |
number. For example, specifying \fIdisk-ratio\fR as \fB0.25\fR means |
197 |
that at least one quarter of disk space should be left free on nodes. |
198 |
|
199 |
.TP |
200 |
.B -p, --print-nodes |
201 |
Prints the before and after node status, in a format designed to allow |
202 |
the user to understand the node's most important parameters. |
203 |
|
204 |
The node list will contain these informations: |
205 |
.RS |
206 |
.TP |
207 |
.B F |
208 |
a character denoting the status of the node, with '-' meaning an |
209 |
offline node, '*' meaning N+1 failure and blank meaning a good node |
210 |
.TP |
211 |
.B Name |
212 |
the node name |
213 |
.TP |
214 |
.B t_mem |
215 |
the total node memory |
216 |
.TP |
217 |
.B n_mem |
218 |
the memory used by the node itself |
219 |
.TP |
220 |
.B i_mem |
221 |
the memory used by instances |
222 |
.TP |
223 |
.B x_mem |
224 |
amount memory which seems to be in use but cannot be determined why or |
225 |
by which instance; usually this means that the hypervisor has some |
226 |
overhead or that there are other reporting errors |
227 |
.TP |
228 |
.B f_mem |
229 |
the free node memory |
230 |
.TP |
231 |
.B r_mem |
232 |
the reserved node memory, which is the amount of free memory needed |
233 |
for N+1 compliance |
234 |
.TP |
235 |
.B t_dsk |
236 |
total disk |
237 |
.TP |
238 |
.B f_dsk |
239 |
free disk |
240 |
.TP |
241 |
.B pcpu |
242 |
the number of physical cpus on the node |
243 |
.TP |
244 |
.B vcpu |
245 |
the number of virtual cpus allocated to primary instances |
246 |
.TP |
247 |
.B pri |
248 |
number of primary instances |
249 |
.TP |
250 |
.B sec |
251 |
number of secondary instances |
252 |
.TP |
253 |
.B p_fmem |
254 |
percent of free memory |
255 |
.TP |
256 |
.B p_fdsk |
257 |
percent of free disk |
258 |
.TP |
259 |
.B r_cpu |
260 |
ratio of virtual to physical cpus |
261 |
.RE |
262 |
|
263 |
.TP |
264 |
.BI "-O " name |
265 |
This option (which can be given multiple times) will mark nodes as |
266 |
being \fIoffline\fR, and instances won't be placed on these nodes. |
267 |
|
268 |
Note that hspace will also mark as offline any nodes which are |
269 |
reported by RAPI as such, or that have "?" in file-based input in any |
270 |
numeric fields. |
271 |
.RE |
272 |
|
273 |
.TP |
274 |
.BI "-n" nodefile ", --nodes=" nodefile |
275 |
The name of the file holding node information (if not collecting via |
276 |
RAPI), instead of the default \fInodes\fR file (but see below how to |
277 |
customize the default value via the environment). |
278 |
|
279 |
.TP |
280 |
.BI "-i" instancefile ", --instances=" instancefile |
281 |
The name of the file holding instance information (if not collecting |
282 |
via RAPI), instead of the default \fIinstances\fR file (but see below |
283 |
how to customize the default value via the environment). |
284 |
|
285 |
.TP |
286 |
.BI "-m" cluster |
287 |
Collect data not from files but directly from the |
288 |
.I cluster |
289 |
given as an argument via RAPI. If the argument doesn't contain a colon |
290 |
(:), then it is converted into a fully-built URL via prepending |
291 |
https:// and appending the default RAPI port, otherwise it's |
292 |
considered a fully-specified URL and is used as-is. |
293 |
|
294 |
.TP |
295 |
.BI "-L[" path "]" |
296 |
Collect data not from files but directly from the master daemon, which |
297 |
is to be contacted via the luxi (an internal Ganeti protocol). An |
298 |
optional \fIpath\fR argument is interpreted as the path to the unix |
299 |
socket on which the master daemon listens; otherwise, the default path |
300 |
used by ganeti when installed with "--localstatedir=/var" is used. |
301 |
|
302 |
.TP |
303 |
.B -v, --verbose |
304 |
Increase the output verbosity. Each usage of this option will increase |
305 |
the verbosity (currently more than 2 doesn't make sense) from the |
306 |
default of one. At verbosity 2 the location of the new instances is |
307 |
shown in the standard error. |
308 |
|
309 |
.TP |
310 |
.B -q, --quiet |
311 |
Decrease the output verbosity. Each usage of this option will decrease |
312 |
the verbosity (less than zero doesn't make sense) from the default of |
313 |
one. |
314 |
|
315 |
.TP |
316 |
.B -V, --version |
317 |
Just show the program version and exit. |
318 |
|
319 |
.SH EXIT STATUS |
320 |
|
321 |
The exist status of the command will be zero, unless for some reason |
322 |
the algorithm fatally failed (e.g. wrong node or instance data). |
323 |
|
324 |
.SH BUGS |
325 |
|
326 |
The algorithm is highly dependent on the number of nodes; its runtime |
327 |
grows exponentially with this number, and as such is impractical for |
328 |
really big clusters. |
329 |
|
330 |
The algorithm doesn't rebalance the cluster or try to get the optimal |
331 |
fit; it just allocates in the best place for the current step, without |
332 |
taking into consideration the impact on future placements. |
333 |
|
334 |
.SH ENVIRONMENT |
335 |
|
336 |
If the variables \fBHTOOLS_NODES\fR and \fBHTOOLS_INSTANCES\fR are |
337 |
present in the environment, they will override the default names for |
338 |
the nodes and instances files. These will have of course no effect |
339 |
when RAPI is used. |
340 |
|
341 |
.SH SEE ALSO |
342 |
.BR hbal "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), " |
343 |
.BR gnt-node "(8)" |
344 |
|
345 |
.SH "COPYRIGHT" |
346 |
.PP |
347 |
Copyright (C) 2009 Google Inc. Permission is granted to copy, |
348 |
distribute and/or modify under the terms of the GNU General Public |
349 |
License as published by the Free Software Foundation; either version 2 |
350 |
of the License, or (at your option) any later version. |
351 |
.PP |
352 |
On Debian systems, the complete text of the GNU General Public License |
353 |
can be found in /usr/share/common-licenses/GPL. |