README 4.22 KB
Newer Older
Iustin Pop's avatar
Iustin Pop committed
1
2
Ganeti Cluster tools (ganeti-htools)
====================================
Iustin Pop's avatar
Iustin Pop committed
3

Iustin Pop's avatar
Iustin Pop committed
4
5
These are some simple cluster tools for fixing common allocation
problems on Ganeti 2.0 clusters.
Iustin Pop's avatar
Iustin Pop committed
6

Iustin Pop's avatar
Iustin Pop committed
7
Note that these tools are most useful for bigger cluster sizes
Iustin Pop's avatar
Iustin Pop committed
8
9
(e.g. more than five or ten machines); at lower sizes, the computations
they do can also be done manually.
Iustin Pop's avatar
Iustin Pop committed
10

Iustin Pop's avatar
Iustin Pop committed
11
12
13
14
15
16
Most of the tools revolve around the concept of keeping the cluster N+1
compliant: this means that in case of failure of any node, the instances
affected can be failed over (via ``gnt-node failover`` or ``gnt-instance
failover``) to their secondary node, and there is enough memory reserved
for this operation without needing to shutdown other instances or
rebalance the cluster.
17

18
19
20
21
22
23
24
25
26
**Quick start** (see the installation section for more details):

- (have the ghc compiler and the prerequisite libraries installed)
- make
- ./hbal -m $cluster -C -p
- look at the original and final cluster layout, and if acceptable,
  execute the given commands


Iustin Pop's avatar
Iustin Pop committed
27
28
Available tools
---------------
Iustin Pop's avatar
Iustin Pop committed
29

Iustin Pop's avatar
Iustin Pop committed
30
Cluster rebalancer
Iustin Pop's avatar
Iustin Pop committed
31
~~~~~~~~~~~~~~~~~~
Iustin Pop's avatar
Iustin Pop committed
32

Iustin Pop's avatar
Iustin Pop committed
33
34
35
The rebalancer uses a simple algorithm to try to get the nodes of the
cluster as equal as possible in their resource usage. It tries to
repeatedly move each instance one step, so that the cluster score
Iustin Pop's avatar
Iustin Pop committed
36
37
38
39
40
becomes better. We stop when no further move can improve the score.

For algorithm details and usage, see the man page hbal(1).

IAllocator plugin
Iustin Pop's avatar
Iustin Pop committed
41
~~~~~~~~~~~~~~~~~
Iustin Pop's avatar
Iustin Pop committed
42

Iustin Pop's avatar
Iustin Pop committed
43
The ``hail`` iallocator plugin can be used for allocations of mirrored
Iustin Pop's avatar
Iustin Pop committed
44
45
46
47
48
and non-mirrored instances and for relocations of mirrored instances. It
needs to be installed in Ganeti's iallocator search path—usually
``/usr/lib/ganeti/iallocators`` or
``/usr/local/lib/ganeti/iallocators``, and after that it can be used via
ganeti's ``--iallocator`` option (in various gnt-node/gnt-instance
49
commands). See the man page hail(1) for more details.
Iustin Pop's avatar
Iustin Pop committed
50

51
52
53
54
55
56
57
58
59
Cluster capacity estimator
~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``hspace`` program will, given an input instance specification,
estimate how many instances of those type can be place on the cluster
before it will become full (as in any new allocation would fail N+1
checks). For more details, see the man page hspace(1).


Iustin Pop's avatar
Iustin Pop committed
60
61
62
Integration with Ganeti
-----------------------

Iustin Pop's avatar
Iustin Pop committed
63
The ``hbal`` and ``hspace`` programs can either get their input from
Iustin Pop's avatar
Iustin Pop committed
64
65
66
67
68
69
70
text files, locally from the master daemon (when run on the master node
of a cluster), or remote from a cluster via RAPI. The "-L" argument
enables local collection (with an optional path to the unix socket). For
online collection via RAPI, the "-m" argument should specify the cluster
or master node name. Only ``hbal`` and ``hspace`` use these arguments,
``hail`` uses the standard iallocator API and thus doesn't need any
special setup (just needs to be installed in the right directory).
Iustin Pop's avatar
Iustin Pop committed
71

72
For generating the text files, a separate tool (``hscan``) is provided
Iustin Pop's avatar
Iustin Pop committed
73
74
75
to automate their gathering if RAPI is available, which is better since
it can extract more precise information. In case RAPI is not usable for
whatever reason, the following two commands should be run::
Iustin Pop's avatar
Iustin Pop committed
76

77
    gnt-node list -oname,mtotal,mnode,mfree,dtotal,dfree,ctotal,offline \
Iustin Pop's avatar
Iustin Pop committed
78
      --separator '|' --no-headers > nodes
79
    gnt-instance list -oname,be/memory,sda_size,be/vcpus,status,pnode,snodes \
Iustin Pop's avatar
Iustin Pop committed
80
81
      --separator '|' --no-head > instances

Iustin Pop's avatar
Iustin Pop committed
82
83
These two files should be saved under the names of *nodes* and
*instances*.
Iustin Pop's avatar
Iustin Pop committed
84

85
86
87
The ``hail`` program gets its data automatically from Ganeti when used
as described in its section.

Iustin Pop's avatar
Iustin Pop committed
88
89
90
91
92
93
Installation
------------

If installing from source, you need a working ghc compiler (6.8 at
least) and some extra Haskell libraries which usually need to be
installed manually:
Iustin Pop's avatar
Iustin Pop committed
94

95
96
97
- json (http://hackage.haskell.org/package/json)
- curl (http://hackage.haskell.org/package/curl)
- network (http://hackage.haskell.org/package/network)
Iustin Pop's avatar
Iustin Pop committed
98

Iustin Pop's avatar
Iustin Pop committed
99
100
Once these are installed, just typing *make* in the top-level directory
should be enough.
Iustin Pop's avatar
Iustin Pop committed
101

Iustin Pop's avatar
Iustin Pop committed
102
103
Only the ``hail`` program needs to be installed in a specific place, the
other tools are not location-dependent.
104
105
106
107

For running the (admittedly small) unittest suite (via *make check*),
the QuickCheck version 1 library is needed.

Iustin Pop's avatar
Iustin Pop committed
108
109
Internal (implementation) documentation is available in the ``apidoc``
directory.
Iustin Pop's avatar
Iustin Pop committed
110

Iustin Pop's avatar
Iustin Pop committed
111
.. vim: set textwidth=72 :
Iustin Pop's avatar
Iustin Pop committed
112
113
.. Local Variables:
.. mode: rst
Iustin Pop's avatar
Iustin Pop committed
114
.. fill-column: 72
Iustin Pop's avatar
Iustin Pop committed
115
.. End: