Statistics
| Branch: | Tag: | Revision:

root / src / README @ 9158a1dd

History | View | Annotate | Download (4.5 kB)

1
Ganeti Cluster tools (ganeti-htools)
2
====================================
3

    
4
**Note:** This document is obsolete and mostly documents the situation
5
before the htools sources were integrated into the ganeti-core
6
codebase. Information about the current situation is available in the
7
``INSTALL`` file in the top-level directory.
8

    
9
These are some simple cluster tools for fixing common allocation
10
problems on Ganeti 2.0 clusters.
11

    
12
Note that these tools are most useful for bigger cluster sizes
13
(e.g. more than five or ten machines); at lower sizes, the computations
14
they do can also be done manually.
15

    
16
Most of the tools revolve around the concept of keeping the cluster N+1
17
compliant: this means that in case of failure of any node, the instances
18
affected can be failed over (via ``gnt-node failover`` or ``gnt-instance
19
failover``) to their secondary node, and there is enough memory reserved
20
for this operation without needing to shutdown other instances or
21
rebalance the cluster.
22

    
23
**Quick start** (see the installation section for more details):
24

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

    
31

    
32
Available tools
33
---------------
34

    
35
Cluster rebalancer
36
~~~~~~~~~~~~~~~~~~
37

    
38
The rebalancer uses a simple algorithm to try to get the nodes of the
39
cluster as equal as possible in their resource usage. It tries to
40
repeatedly move each instance one step, so that the cluster score
41
becomes better. We stop when no further move can improve the score.
42

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

    
45
IAllocator plugin
46
~~~~~~~~~~~~~~~~~
47

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

    
56
Cluster capacity estimator
57
~~~~~~~~~~~~~~~~~~~~~~~~~~
58

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

    
64

    
65
Integration with Ganeti
66
-----------------------
67

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

    
77
For generating the text files, a separate tool (``hscan``) is provided
78
to automate their gathering if RAPI is available, which is better since
79
it can extract more precise information. In case RAPI is not usable for
80
whatever reason, ``gnt-node list`` and ``gnt-instance list`` could be
81
used, and their output concatenated in a single file, separated by one
82
blank line. If you need to do this manually, you'll need to check the
83
sources to see which fields are needed exactly.
84

    
85

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

    
89
Installation
90
------------
91

    
92
If installing from source, you need a working ghc compiler (6.8 at
93
least) and some extra Haskell libraries which usually need to be
94
installed manually:
95

    
96
- `json <http://hackage.haskell.org/package/json>`_
97
- `curl <http://hackage.haskell.org/package/curl>`_
98
- `network <http://hackage.haskell.org/package/network>`_
99
- `parallel <http://hackage.haskell.org/package/parallel>`_, version 1.x
100

    
101
Once these are installed, just typing *make* in the top-level directory
102
should be enough. If you edit the documentation sources, you will need
103
the ``pandoc`` program to rebuilt it.
104

    
105
Only the ``hail`` program needs to be installed in a specific place, the
106
other tools are not location-dependent.
107

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

    
111
Internal (implementation) documentation is available in the ``apidoc``
112
directory.
113

    
114
.. vim: set textwidth=72 :
115
.. Local Variables:
116
.. mode: rst
117
.. fill-column: 72
118
.. End: