README 4.4 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
8
9
10
Note that these tools are most useful for bigger cluster sizes
(e.g. more than five or ten machines); at lower sizes, the
computations they do can also be done manually.

11
12
13
14
15
16
17
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.

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
becomes better. We stop when no further move can improve the score.

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

Iustin Pop's avatar
Iustin Pop committed
40
Cluster N+1 solver
Iustin Pop's avatar
Iustin Pop committed
41
~~~~~~~~~~~~~~~~~~
Iustin Pop's avatar
Iustin Pop committed
42
43
44
45
46
47

This program runs a very simple brute force algorithm over the instance
placement space in order to determine the shortest number of replace-disks
needed to fix the cluster. Note this means we won't get a balanced cluster,
just one that passes N+1 checks.

Iustin Pop's avatar
Iustin Pop committed
48
49
50
For algorithm details and usage, see the man page hn1(1).

.. note:: This program is deprecated, hbal should be used instead.
Iustin Pop's avatar
Iustin Pop committed
51

Iustin Pop's avatar
Iustin Pop committed
52
IAllocator plugin
Iustin Pop's avatar
Iustin Pop committed
53
~~~~~~~~~~~~~~~~~
Iustin Pop's avatar
Iustin Pop committed
54

Iustin Pop's avatar
Iustin Pop committed
55
56
57
58
The ``hail`` iallocator plugin can be used for allocations of mirrored
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
59
60
61
``/usr/local/lib/ganeti/iallocators``, and after that it can be used
via ganeti's ``--iallocator`` option (in various gnt-node/gnt-instance
commands). See the man page hail(1) for more details.
Iustin Pop's avatar
Iustin Pop committed
62

63
64
65
66
67
68
69
70
71
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
72
73
74
Integration with Ganeti
-----------------------

75
76
77
78
79
80
The ``hbal``, ``hspace`` and ``hn1`` programs can either get their
input from text files, or online from a cluster via RAPI. For online
collection via RAPI, the "-m" argument to both hn1 and hbal should
specify the cluster or master node name. ``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
81

82
83
84
85
For generating the text files, a separate tool (``hscan``) is provided
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
86

Iustin Pop's avatar
Iustin Pop committed
87
    gnt-node list -oname,mtotal,mnode,mfree,dtotal,dfree,offline \
Iustin Pop's avatar
Iustin Pop committed
88
      --separator '|' --no-headers > nodes
89
    gnt-instance list -oname,be/memory,sda_size,be/vcpus,status,pnode,snodes \
Iustin Pop's avatar
Iustin Pop committed
90
91
      --separator '|' --no-head > instances

Iustin Pop's avatar
Iustin Pop committed
92
93
These two files should be saved under the names of *nodes* and
*instances*.
Iustin Pop's avatar
Iustin Pop committed
94

95
96
97
The ``hail`` program gets its data automatically from Ganeti when used
as described in its section.

Iustin Pop's avatar
Iustin Pop committed
98
99
100
101
102
103
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
104

105
106
- json (http://hackage.haskell.org/cgi-bin/hackage-scripts/package/json)
- curl (http://hackage.haskell.org/cgi-bin/hackage-scripts/package/curl)
Iustin Pop's avatar
Iustin Pop committed
107

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

111
112
113
114
115
116
Only the ``hail`` program needs to be installed in a specific place,
the other tools are not location-dependent.

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

Iustin Pop's avatar
Iustin Pop committed
117
118
Internal (implementation) documentation is available in the ``apidoc``
directory.
Iustin Pop's avatar
Iustin Pop committed
119
120
121
122

.. Local Variables:
.. mode: rst
.. End: