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