root / man / htools.rst @ 332b1340
History | View | Annotate | Download (8.5 kB)
1 |
HTOOLS(1) Ganeti | Version @GANETI_VERSION@ |
---|---|
2 |
=========================================== |
3 |
|
4 |
NAME |
5 |
---- |
6 |
|
7 |
htools - Cluster allocation and placement tools for Ganeti |
8 |
|
9 |
SYNOPSIS |
10 |
-------- |
11 |
|
12 |
**hbal** |
13 |
cluster balancer |
14 |
|
15 |
**hcheck** |
16 |
cluster checker |
17 |
|
18 |
**hspace** |
19 |
cluster capacity computation |
20 |
|
21 |
**hail** |
22 |
IAllocator plugin |
23 |
|
24 |
**hscan** |
25 |
saves cluster state for later reuse |
26 |
|
27 |
**hinfo** |
28 |
cluster information printer |
29 |
|
30 |
|
31 |
DESCRIPTION |
32 |
----------- |
33 |
|
34 |
|
35 |
``htools`` is a suite of tools designed to help with allocation/movement |
36 |
of instances and balancing of Ganeti clusters. ``htools`` is also the |
37 |
generic binary that must be symlinked or hardlinked under each tool's |
38 |
name in order to perform the different functions. Alternatively, the |
39 |
environment variable HTOOLS can be used to set the desired role. |
40 |
|
41 |
Installed as ``hbal``, it computes and optionally executes a suite of |
42 |
instance moves in order to balance the cluster. |
43 |
|
44 |
Installed as ``hcheck``, it preforms cluster checks and optionally |
45 |
simulates rebalancing with all the ``hbal`` options available. |
46 |
|
47 |
Installed as ``hspace``, it computes how many additional instances can |
48 |
be fit on a cluster, while maintaining N+1 status. It can run on models |
49 |
of existing clusters or of simulated clusters. |
50 |
|
51 |
Installed as ``hail``, it acts as an IAllocator plugin, i.e. it is used |
52 |
by Ganeti to compute new instance allocations and instance moves. |
53 |
|
54 |
Installed as ``hscan``, it scans the local or remote cluster state and |
55 |
saves it to files which can later be reused by the other roles. |
56 |
|
57 |
Installed as ``hinfo``, it prints information about the current cluster |
58 |
state. |
59 |
|
60 |
COMMON OPTIONS |
61 |
-------------- |
62 |
|
63 |
Options behave the same in all program modes, but not all program modes |
64 |
support all options. Some common options are: |
65 |
|
66 |
-p, \--print-nodes |
67 |
Prints the node status, in a format designed to allow the user to |
68 |
understand the node's most important parameters. If the command in |
69 |
question makes a cluster transition (e.g. balancing or allocation), |
70 |
then usually both the initial and final node status is printed. |
71 |
|
72 |
It is possible to customise the listed information by passing a |
73 |
comma-separated list of field names to this option (the field list |
74 |
is currently undocumented), or to extend the default field list by |
75 |
prefixing the additional field list with a plus sign. By default, |
76 |
the node list will contain the following information: |
77 |
|
78 |
F |
79 |
a character denoting the status of the node, with '-' meaning an |
80 |
offline node, '*' meaning N+1 failure and blank meaning a good |
81 |
node |
82 |
|
83 |
Name |
84 |
the node name |
85 |
|
86 |
t_mem |
87 |
the total node memory |
88 |
|
89 |
n_mem |
90 |
the memory used by the node itself |
91 |
|
92 |
i_mem |
93 |
the memory used by instances |
94 |
|
95 |
x_mem |
96 |
amount memory which seems to be in use but cannot be determined |
97 |
why or by which instance; usually this means that the hypervisor |
98 |
has some overhead or that there are other reporting errors |
99 |
|
100 |
f_mem |
101 |
the free node memory |
102 |
|
103 |
r_mem |
104 |
the reserved node memory, which is the amount of free memory |
105 |
needed for N+1 compliance |
106 |
|
107 |
t_dsk |
108 |
total disk |
109 |
|
110 |
f_dsk |
111 |
free disk |
112 |
|
113 |
pcpu |
114 |
the number of physical cpus on the node |
115 |
|
116 |
vcpu |
117 |
the number of virtual cpus allocated to primary instances |
118 |
|
119 |
pcnt |
120 |
number of primary instances |
121 |
|
122 |
scnt |
123 |
number of secondary instances |
124 |
|
125 |
p_fmem |
126 |
percent of free memory |
127 |
|
128 |
p_fdsk |
129 |
percent of free disk |
130 |
|
131 |
r_cpu |
132 |
ratio of virtual to physical cpus |
133 |
|
134 |
lCpu |
135 |
the dynamic CPU load (if the information is available) |
136 |
|
137 |
lMem |
138 |
the dynamic memory load (if the information is available) |
139 |
|
140 |
lDsk |
141 |
the dynamic disk load (if the information is available) |
142 |
|
143 |
lNet |
144 |
the dynamic net load (if the information is available) |
145 |
|
146 |
-t *datafile*, \--text-data=*datafile* |
147 |
Backend specification: the name of the file holding node and instance |
148 |
information (if not collecting via RAPI or LUXI). This or one of the |
149 |
other backends must be selected. The option is described in the man |
150 |
page **htools**(1). |
151 |
|
152 |
The file should contain text data, line-based, with two empty lines |
153 |
separating sections. The lines themselves are column-based, with the |
154 |
pipe symbol (``|``) acting as separator. |
155 |
|
156 |
The first section contains group data, with two columns: |
157 |
|
158 |
- group name |
159 |
- group uuid |
160 |
|
161 |
The second sections contains node data, with the following columns: |
162 |
|
163 |
- node name |
164 |
- node total memory |
165 |
- node free memory |
166 |
- node total disk |
167 |
- node free disk |
168 |
- node physical cores |
169 |
- offline field (as ``Y`` or ``N``) |
170 |
- group UUID |
171 |
- node spindle count |
172 |
|
173 |
The third section contains instance data, with the fields: |
174 |
|
175 |
- instance name |
176 |
- instance memory |
177 |
- instance disk size |
178 |
- instance vcpus |
179 |
- instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``) |
180 |
- instance ``auto_balance`` flag (see man page **gnt-instance** (7)) |
181 |
- instance primary node |
182 |
- instance secondary node(s), if any |
183 |
- instance disk type (e.g. ``plain`` or ``drbd``) |
184 |
- instance tags |
185 |
|
186 |
The fourth section contains the cluster tags, with one tag per line |
187 |
(no columns/no column processing). |
188 |
|
189 |
The fifth section contains the ipolicies of the cluster and the node |
190 |
groups, in the following format (separated by ``|``): |
191 |
|
192 |
- owner (empty if cluster, group name otherwise) |
193 |
- standard, min, max instance specs, containing the following values |
194 |
separated by commas: |
195 |
- memory size |
196 |
- cpu count |
197 |
- disk size |
198 |
- disk count |
199 |
- nic count |
200 |
- disk templates |
201 |
- vcpu ratio |
202 |
- spindle ratio |
203 |
|
204 |
-m *cluster* |
205 |
Backend specification: collect data directly from the *cluster* given |
206 |
as an argument via RAPI. If the argument doesn't contain a colon (:), |
207 |
then it is converted into a fully-built URL via prepending |
208 |
``https://`` and appending the default RAPI port, otherwise it is |
209 |
considered a fully-specified URL and used as-is. |
210 |
|
211 |
-L [*path*] |
212 |
Backend specification: collect data directly from the master daemon, |
213 |
which is to be contacted via LUXI (an internal Ganeti protocol). An |
214 |
optional *path* argument is interpreted as the path to the unix socket |
215 |
on which the master daemon listens; otherwise, the default path used |
216 |
by Ganeti (configured at build time) is used. |
217 |
|
218 |
-I|\--ialloc-src *path* |
219 |
Backend specification: load data directly from an iallocator request |
220 |
(as produced by Ganeti when doing an iallocator call). The iallocator |
221 |
request is read from specified path. |
222 |
|
223 |
\--simulate *description* |
224 |
Backend specification: instead of using actual data, build an empty |
225 |
cluster given a node description. The *description* parameter must be |
226 |
a comma-separated list of five elements, describing in order: |
227 |
|
228 |
- the allocation policy for this node group (*preferred*, *allocable* |
229 |
or *unallocable*, or alternatively the short forms *p*, *a* or *u*) |
230 |
- the number of nodes in the cluster |
231 |
- the disk size of the nodes (default in mebibytes, units can be used) |
232 |
- the memory size of the nodes (default in mebibytes, units can be used) |
233 |
- the cpu core count for the nodes |
234 |
- the spindle count for the nodes |
235 |
|
236 |
An example description would be **preferred,20,100G,16g,4,2** |
237 |
describing a 20-node cluster where each node has 100GB of disk space, |
238 |
16GiB of memory, 4 CPU cores and 2 disk spindles. Note that all nodes |
239 |
must have the same specs currently. |
240 |
|
241 |
This option can be given multiple times, and each new use defines a |
242 |
new node group. Hence different node groups can have different |
243 |
allocation policies and node count/specifications. |
244 |
|
245 |
-v, \--verbose |
246 |
Increase the output verbosity. Each usage of this option will |
247 |
increase the verbosity (currently more than 2 doesn't make sense) |
248 |
from the default of one. |
249 |
|
250 |
-q, \--quiet |
251 |
Decrease the output verbosity. Each usage of this option will |
252 |
decrease the verbosity (less than zero doesn't make sense) from the |
253 |
default of one. |
254 |
|
255 |
-V, \--version |
256 |
Just show the program version and exit. |
257 |
|
258 |
UNITS |
259 |
~~~~~ |
260 |
|
261 |
Some options accept not simply numerical values, but numerical values |
262 |
together with a unit. By default, such unit-accepting options use |
263 |
mebibytes. Using the lower-case letters of *m*, *g* and *t* (or their |
264 |
longer equivalents of *mib*, *gib*, *tib*, for which case doesn't |
265 |
matter) explicit binary units can be selected. Units in the SI system |
266 |
can be selected using the upper-case letters of *M*, *G* and *T* (or |
267 |
their longer equivalents of *MB*, *GB*, *TB*, for which case doesn't |
268 |
matter). |
269 |
|
270 |
More details about the difference between the SI and binary systems can |
271 |
be read in the *units(7)* man page. |
272 |
|
273 |
ENVIRONMENT |
274 |
----------- |
275 |
|
276 |
The environment variable ``HTOOLS`` can be used instead of |
277 |
renaming/symlinking the programs; simply set it to the desired role and |
278 |
then the name of the program is no longer used. |
279 |
|
280 |
.. vim: set textwidth=72 : |
281 |
.. Local Variables: |
282 |
.. mode: rst |
283 |
.. fill-column: 72 |
284 |
.. End: |