code.grnet.gr Git - ganeti-local/blob - README

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