root / hspace.1 @ 877d0386
History | View | Annotate | Download (6.9 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 "[-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 |
.BI "[--max-cpu " cpu-ratio "]" |
17 |
.BI "[--min-disk " disk-ratio "]" |
18 |
|
19 |
.B hspace |
20 |
.B --version |
21 |
|
22 |
.SH DESCRIPTION |
23 |
hspace computes how many additional instances can be fit on a cluster, |
24 |
while maintaining N+1 status. |
25 |
|
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 |
29 |
iallocator plugin. |
30 |
|
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. |
33 |
|
34 |
.SH OPTIONS |
35 |
The options that can be passed to the program are as follows: |
36 |
|
37 |
.TP |
38 |
.BI "--memory " mem |
39 |
The memory size of the instances to be placed (defaults to 4GiB). |
40 |
|
41 |
.TP |
42 |
.BI "--disk " disk |
43 |
The disk size of the instances to be placed (defaults to 100GiB). |
44 |
|
45 |
.TP |
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. |
49 |
|
50 |
.TP |
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 |
57 |
on it. |
58 |
|
59 |
.TP |
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. |
64 |
|
65 |
.TP |
66 |
.B -p, --print-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. |
69 |
|
70 |
The node list will contain these informations: |
71 |
.RS |
72 |
.TP |
73 |
.B F |
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 |
76 |
.TP |
77 |
.B Name |
78 |
the node name |
79 |
.TP |
80 |
.B t_mem |
81 |
the total node memory |
82 |
.TP |
83 |
.B n_mem |
84 |
the memory used by the node itself |
85 |
.TP |
86 |
.B i_mem |
87 |
the memory used by instances |
88 |
.TP |
89 |
.B x_mem |
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 |
93 |
.TP |
94 |
.B f_mem |
95 |
the free node memory |
96 |
.TP |
97 |
.B r_mem |
98 |
the reserved node memory, which is the amount of free memory needed |
99 |
for N+1 compliance |
100 |
.TP |
101 |
.B t_dsk |
102 |
total disk |
103 |
.TP |
104 |
.B f_dsk |
105 |
free disk |
106 |
.TP |
107 |
.B pcpu |
108 |
the number of physical cpus on the node |
109 |
.TP |
110 |
.B vcpu |
111 |
the number of virtual cpus allocated to primary instances |
112 |
.TP |
113 |
.B pri |
114 |
number of primary instances |
115 |
.TP |
116 |
.B sec |
117 |
number of secondary instances |
118 |
.TP |
119 |
.B p_fmem |
120 |
percent of free memory |
121 |
.TP |
122 |
.B p_fdsk |
123 |
percent of free disk |
124 |
.TP |
125 |
.B r_cpu |
126 |
ratio of virtual to physical cpus |
127 |
.RE |
128 |
|
129 |
.TP |
130 |
.BI "-O " name |
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. |
133 |
|
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 |
136 |
numeric fields. |
137 |
.RE |
138 |
|
139 |
.TP |
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). |
144 |
|
145 |
.TP |
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). |
150 |
|
151 |
.TP |
152 |
.BI "-m" cluster |
153 |
Collect data not from files but directly from the |
154 |
.I cluster |
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. |
159 |
|
160 |
.TP |
161 |
.B -v, --verbose |
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. |
166 |
|
167 |
.TP |
168 |
.B -q, --quiet |
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 |
171 |
one. |
172 |
|
173 |
.TP |
174 |
.B -V, --version |
175 |
Just show the program version and exit. |
176 |
|
177 |
.SH EXIT STATUS |
178 |
|
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). |
181 |
|
182 |
.SH BUGS |
183 |
|
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 |
186 |
really big clusters. |
187 |
|
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. |
191 |
|
192 |
.SH EXAMPLE |
193 |
|
194 |
.SS Default output |
195 |
|
196 |
.in +4n |
197 |
.nf |
198 |
.RB "$" " hspace --mem 16 --disk 16 --req-nodes 2" |
199 |
Initial score: 0.38988095 |
200 |
Initial instances: 3 |
201 |
Initial free RAM: 546 |
202 |
Initial free disk: 260600 |
203 |
Final score: 0.32638889 |
204 |
Final instances: 7 |
205 |
Final free RAM: 482 |
206 |
Final free disk: 260472 |
207 |
Usage: 0.43 |
208 |
Allocations: 4 |
209 |
.fi |
210 |
.in |
211 |
|
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. |
215 |
|
216 |
.SS Verbose output |
217 |
|
218 |
For the same cluster as above: |
219 |
.in +4n |
220 |
.nf |
221 |
.RB "$" " hspace --mem 16 --disk 16 --req-nodes 2 -v" |
222 |
Initial score: 0.38988095 |
223 |
Initial instances: 3 |
224 |
Initial free RAM: 546 |
225 |
Initial free disk: 260600 |
226 |
Final score: 0.32638889 |
227 |
Final instances: 7 |
228 |
Final free RAM: 482 |
229 |
Final free disk: 260472 |
230 |
Usage: 0.43 |
231 |
Allocations: 4 |
232 |
Inst: new-0 node2 node1 |
233 |
Inst: new-1 node2 node1 |
234 |
Inst: new-2 node2 node1 |
235 |
Inst: new-3 node2 node1 |
236 |
.fi |
237 |
.in |
238 |
|
239 |
The output now includes the placement for the new instances (named |
240 |
\fBnew-\fInumber\fR). |
241 |
|
242 |
.SH ENVIRONMENT |
243 |
|
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 |
247 |
when RAPI is used. |
248 |
|
249 |
.SH SEE ALSO |
250 |
.BR hbal "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), " |
251 |
.BR gnt-node "(8)" |
252 |
|
253 |
.SH "COPYRIGHT" |
254 |
.PP |
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. |
259 |
.PP |
260 |
On Debian systems, the complete text of the GNU General Public License |
261 |
can be found in /usr/share/common-licenses/GPL. |