Statistics
| Branch: | Tag: | Revision:

root / htools / README @ 135f64a3

History | View | Annotate | Download (4.5 kB)

1 dc384cf0 Iustin Pop
Ganeti Cluster tools (ganeti-htools)
2 dc384cf0 Iustin Pop
====================================
3 dc384cf0 Iustin Pop
4 b7448942 Iustin Pop
**Note:** This document is obsolete and mostly documents the situation
5 b7448942 Iustin Pop
before the htools sources were integrated into the ganeti-core
6 b7448942 Iustin Pop
codebase. Information about the current situation is available in the
7 b7448942 Iustin Pop
``INSTALL`` file in the top-level directory.
8 b7448942 Iustin Pop
9 dc384cf0 Iustin Pop
These are some simple cluster tools for fixing common allocation
10 dc384cf0 Iustin Pop
problems on Ganeti 2.0 clusters.
11 dc384cf0 Iustin Pop
12 dc384cf0 Iustin Pop
Note that these tools are most useful for bigger cluster sizes
13 dc384cf0 Iustin Pop
(e.g. more than five or ten machines); at lower sizes, the computations
14 dc384cf0 Iustin Pop
they do can also be done manually.
15 dc384cf0 Iustin Pop
16 dc384cf0 Iustin Pop
Most of the tools revolve around the concept of keeping the cluster N+1
17 dc384cf0 Iustin Pop
compliant: this means that in case of failure of any node, the instances
18 dc384cf0 Iustin Pop
affected can be failed over (via ``gnt-node failover`` or ``gnt-instance
19 dc384cf0 Iustin Pop
failover``) to their secondary node, and there is enough memory reserved
20 dc384cf0 Iustin Pop
for this operation without needing to shutdown other instances or
21 dc384cf0 Iustin Pop
rebalance the cluster.
22 dc384cf0 Iustin Pop
23 dc384cf0 Iustin Pop
**Quick start** (see the installation section for more details):
24 dc384cf0 Iustin Pop
25 dc384cf0 Iustin Pop
- (have the ghc compiler and the prerequisite libraries installed)
26 dc384cf0 Iustin Pop
- ``make``
27 dc384cf0 Iustin Pop
- ``./hbal -m $cluster -C -p``
28 dc384cf0 Iustin Pop
- look at the original and final cluster layout, and if acceptable,
29 dc384cf0 Iustin Pop
  execute the given commands
30 dc384cf0 Iustin Pop
31 dc384cf0 Iustin Pop
32 dc384cf0 Iustin Pop
Available tools
33 dc384cf0 Iustin Pop
---------------
34 dc384cf0 Iustin Pop
35 dc384cf0 Iustin Pop
Cluster rebalancer
36 dc384cf0 Iustin Pop
~~~~~~~~~~~~~~~~~~
37 dc384cf0 Iustin Pop
38 dc384cf0 Iustin Pop
The rebalancer uses a simple algorithm to try to get the nodes of the
39 dc384cf0 Iustin Pop
cluster as equal as possible in their resource usage. It tries to
40 dc384cf0 Iustin Pop
repeatedly move each instance one step, so that the cluster score
41 dc384cf0 Iustin Pop
becomes better. We stop when no further move can improve the score.
42 dc384cf0 Iustin Pop
43 dc384cf0 Iustin Pop
For algorithm details and usage, see the man page ``hbal(1)``.
44 dc384cf0 Iustin Pop
45 dc384cf0 Iustin Pop
IAllocator plugin
46 dc384cf0 Iustin Pop
~~~~~~~~~~~~~~~~~
47 dc384cf0 Iustin Pop
48 dc384cf0 Iustin Pop
The ``hail`` iallocator plugin can be used for allocations of mirrored
49 dc384cf0 Iustin Pop
and non-mirrored instances and for relocations of mirrored instances. It
50 dc384cf0 Iustin Pop
needs to be installed in Ganeti's iallocator search path—usually
51 dc384cf0 Iustin Pop
``/usr/lib/ganeti/iallocators`` or
52 dc384cf0 Iustin Pop
``/usr/local/lib/ganeti/iallocators``, and after that it can be used via
53 dc384cf0 Iustin Pop
ganeti's ``--iallocator`` option (in various gnt-node/gnt-instance
54 dc384cf0 Iustin Pop
commands). See the man page ``hail(1)`` for more details.
55 dc384cf0 Iustin Pop
56 dc384cf0 Iustin Pop
Cluster capacity estimator
57 dc384cf0 Iustin Pop
~~~~~~~~~~~~~~~~~~~~~~~~~~
58 dc384cf0 Iustin Pop
59 dc384cf0 Iustin Pop
The ``hspace`` program will, given an input instance specification,
60 dc384cf0 Iustin Pop
estimate how many instances of those type can be place on the cluster
61 dc384cf0 Iustin Pop
before it will become full (as in any new allocation would fail N+1
62 dc384cf0 Iustin Pop
checks). For more details, see the man page hspace(1).
63 dc384cf0 Iustin Pop
64 dc384cf0 Iustin Pop
65 dc384cf0 Iustin Pop
Integration with Ganeti
66 dc384cf0 Iustin Pop
-----------------------
67 dc384cf0 Iustin Pop
68 dc384cf0 Iustin Pop
The ``hbal`` and ``hspace`` programs can either get their input from
69 dc384cf0 Iustin Pop
text files, locally from the master daemon (when run on the master node
70 dc384cf0 Iustin Pop
of a cluster), or remote from a cluster via RAPI. The "-L" argument
71 dc384cf0 Iustin Pop
enables local collection (with an optional path to the unix socket). For
72 dc384cf0 Iustin Pop
online collection via RAPI, the "-m" argument should specify the cluster
73 dc384cf0 Iustin Pop
or master node name. Only ``hbal`` and ``hspace`` use these arguments,
74 dc384cf0 Iustin Pop
``hail`` uses the standard iallocator API and thus doesn't need any
75 dc384cf0 Iustin Pop
special setup (just needs to be installed in the right directory).
76 dc384cf0 Iustin Pop
77 dc384cf0 Iustin Pop
For generating the text files, a separate tool (``hscan``) is provided
78 dc384cf0 Iustin Pop
to automate their gathering if RAPI is available, which is better since
79 dc384cf0 Iustin Pop
it can extract more precise information. In case RAPI is not usable for
80 dc384cf0 Iustin Pop
whatever reason, ``gnt-node list`` and ``gnt-instance list`` could be
81 dc384cf0 Iustin Pop
used, and their output concatenated in a single file, separated by one
82 dc384cf0 Iustin Pop
blank line. If you need to do this manually, you'll need to check the
83 dc384cf0 Iustin Pop
sources to see which fields are needed exactly.
84 dc384cf0 Iustin Pop
85 dc384cf0 Iustin Pop
86 dc384cf0 Iustin Pop
The ``hail`` program gets its data automatically from Ganeti when used
87 dc384cf0 Iustin Pop
as described in its section.
88 dc384cf0 Iustin Pop
89 dc384cf0 Iustin Pop
Installation
90 dc384cf0 Iustin Pop
------------
91 dc384cf0 Iustin Pop
92 dc384cf0 Iustin Pop
If installing from source, you need a working ghc compiler (6.8 at
93 dc384cf0 Iustin Pop
least) and some extra Haskell libraries which usually need to be
94 dc384cf0 Iustin Pop
installed manually:
95 dc384cf0 Iustin Pop
96 dc384cf0 Iustin Pop
- `json <http://hackage.haskell.org/package/json>`_
97 dc384cf0 Iustin Pop
- `curl <http://hackage.haskell.org/package/curl>`_
98 dc384cf0 Iustin Pop
- `network <http://hackage.haskell.org/package/network>`_
99 dc384cf0 Iustin Pop
- `parallel <http://hackage.haskell.org/package/parallel>`_, version 1.x
100 dc384cf0 Iustin Pop
101 dc384cf0 Iustin Pop
Once these are installed, just typing *make* in the top-level directory
102 dc384cf0 Iustin Pop
should be enough. If you edit the documentation sources, you will need
103 dc384cf0 Iustin Pop
the ``pandoc`` program to rebuilt it.
104 dc384cf0 Iustin Pop
105 dc384cf0 Iustin Pop
Only the ``hail`` program needs to be installed in a specific place, the
106 dc384cf0 Iustin Pop
other tools are not location-dependent.
107 dc384cf0 Iustin Pop
108 dc384cf0 Iustin Pop
For running the (admittedly small) unittest suite (via *make check*),
109 b7448942 Iustin Pop
the QuickCheck version 2 library is needed.
110 dc384cf0 Iustin Pop
111 dc384cf0 Iustin Pop
Internal (implementation) documentation is available in the ``apidoc``
112 dc384cf0 Iustin Pop
directory.
113 dc384cf0 Iustin Pop
114 dc384cf0 Iustin Pop
.. vim: set textwidth=72 :
115 dc384cf0 Iustin Pop
.. Local Variables:
116 dc384cf0 Iustin Pop
.. mode: rst
117 dc384cf0 Iustin Pop
.. fill-column: 72
118 dc384cf0 Iustin Pop
.. End: