Statistics
| Branch: | Tag: | Revision:

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.