|
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.
|