Merge branch 'stable-2.15' into stable-2.16
[ganeti-github.git] / man / harep.rst
1 HAREP(1) Ganeti | Version @GANETI_VERSION@
2 ==========================================
3
4 NAME
5 ----
6
7 harep - Ganeti auto-repair tool
8
9 SYNOPSIS
10 --------
11
12 **harep** [ [**-L** | **\--luxi** ] = *socket* ] [ --job-delay = *seconds* ]
13 [ --dry-run ]
14
15 **harep** \--version
16
17 DESCRIPTION
18 -----------
19
20 Harep is the Ganeti auto-repair tool. It is able to detect that an instance is
21 broken and to generate a sequence of jobs that will fix it, in accordance to the
22 policies set by the administrator. At the moment, only repairs for instances
23 using the disk templates ``plain`` or ``drbd`` are supported.
24
25 Harep is able to recognize what state an instance is in (healthy, suspended,
26 needs repair, repair disallowed, pending repair, repair failed)
27 and to lead it through a sequence of steps that will bring the instance
28 back to the healthy state. Therefore, harep is mainly meant to be run regularly
29 and frequently using a cron job, so that it can actually follow the instance
30 along all the process. At every run, harep will update the tags it adds to
31 instances that describe its repair status, and will submit jobs that actually
32 perform the required repair operations.
33
34 By default, harep only reports on the health status of instances, but doesn't
35 perform any action, as they might be potentially dangerous. Therefore, harep
36 will only touch instances that it has been explicitly authorized to work on.
37
38 The tags enabling harep, can be associated to single instances, or to a
39 nodegroup or to the whole cluster, therefore affecting all the instances they
40 contain. The possible tags share the common structure::
41
42  ganeti:watcher:autorepair:<type>
43
44 where ``<type>`` can have the following values:
45
46 * ``fix-storage``: allow disk replacement or fix the backend without affecting
47   the instance itself (broken DRBD secondary)
48 * ``migrate``: allow instance migration. Note, however, that current harep does
49   not submit migrate jobs; so, currently, this permission level is equivalent to
50   ``fix-storage``.
51 * ``failover``: allow instance reboot on the secondary; this action is taken, if
52   the primary node is offline.
53 * ``reinstall``: allow disks to be recreated and the instance to be reinstalled
54
55 Each element in the list of tags, includes all the authorizations of the
56 previous one, with ``fix-storage`` being the least powerful and ``reinstall``
57 being the most powerful.
58
59 In case multiple autorepair tags act on the same instance, only one can actually
60 be active. The conflict is solved according to the following rules:
61
62 #. if multiple tags are in the same object, the least destructive takes
63    precedence.
64
65 #. if the tags are across objects, the nearest tag wins.
66
67 Example:
68 A cluster has instances I1 and I2, where I1 has the ``failover`` tag, and
69 the cluster has both ``fix-storage`` and ``reinstall``.
70 The I1 instance will be allowed to ``failover``, the I2 instance only to
71 ``fix-storage``.
72
73 LIMITATIONS
74 -----------
75
76 Harep doesn't do any hardware failure detection on its own, it relies on
77 nodes being marked as offline by the administrator.
78
79 Also harep currently works only for instances with the ``drbd`` and
80 ``plain`` disk templates.
81
82 Using the data model of **htools**\(1), harep cannot distinguish between drained
83 and offline nodes. In particular, it will (permission provided) failover
84 instances also in situations where a migration would have been enough.
85 In particular, handling of node draining is better done using **hbal**\(1),
86 which will always submit migration jobs, however is the permission to fall
87 back to failover.
88
89 These issues will be addressed by a new maintenance daemon in
90 future Ganeti versions, which will supersede harep.
91
92
93 OPTIONS
94 -------
95
96 The options that can be passed to the program are as follows:
97
98 -L *socket*, \--luxi=*socket*
99   collect data via Luxi, optionally using the given *socket* path.
100
101 \--job-delay=*seconds*
102   insert this much delay before the execution of repair jobs to allow the tool
103   to continue processing instances.
104
105 \--dry-run
106   only show which operations would be carried out, but do nothing, even on
107   instances where tags grant the appropriate permissions. Note that harep
108   keeps the state of repair operations in instance tags; therefore, only
109   the operations of the next round of actions can be inspected.
110
111 .. vim: set textwidth=72 :
112 .. Local Variables:
113 .. mode: rst
114 .. fill-column: 72
115 .. End: