ha-manager: fix copy-paste error
[pve-docs.git] / ha-manager.adoc
CommitLineData
22653ac8
DM
1[[chapter-ha-manager]]
2ifdef::manvolnum[]
3PVE({manvolnum})
4================
5include::attributes.txt[]
6
7NAME
8----
9
734404b4 10ha-manager - Proxmox VE HA Manager
22653ac8
DM
11
12SYNOPSYS
13--------
14
15include::ha-manager.1-synopsis.adoc[]
16
17DESCRIPTION
18-----------
19endif::manvolnum[]
20
21ifndef::manvolnum[]
22High Availability
23=================
24include::attributes.txt[]
25endif::manvolnum[]
26
b5266e9f
DM
27
28Our modern society depends heavily on information provided by
29computers over the network. Mobile devices amplified that dependency,
30because people can access the network any time from anywhere. If you
31provide such services, it is very important that they are available
32most of the time.
33
34We can mathematically define the availability as the ratio of (A) the
35total time a service is capable of being used during a given interval
36to (B) the length of the interval. It is normally expressed as a
37percentage of uptime in a given year.
38
39.Availability - Downtime per Year
40[width="60%",cols="<d,d",options="header"]
41|===========================================================
42|Availability % |Downtime per year
43|99 |3.65 days
44|99.9 |8.76 hours
45|99.99 |52.56 minutes
46|99.999 |5.26 minutes
47|99.9999 |31.5 seconds
48|99.99999 |3.15 seconds
49|===========================================================
50
04bde502
DM
51There are several ways to increase availability. The most elegant
52solution is to rewrite your software, so that you can run it on
53several host at the same time. The software itself need to have a way
2af6af05 54to detect errors and do failover. This is relatively easy if you just
04bde502
DM
55want to serve read-only web pages. But in general this is complex, and
56sometimes impossible because you cannot modify the software
57yourself. The following solutions works without modifying the
58software:
59
8c1189b6 60* Use reliable ``server'' components
04bde502
DM
61
62NOTE: Computer components with same functionality can have varying
2af6af05 63reliability numbers, depending on the component quality. Most vendors
8c1189b6 64sell components with higher reliability as ``server'' components -
04bde502 65usually at higher price.
b5266e9f
DM
66
67* Eliminate single point of failure (redundant components)
8c1189b6
FG
68** use an uninterruptible power supply (UPS)
69** use redundant power supplies on the main boards
70** use ECC-RAM
71** use redundant network hardware
72** use RAID for local storage
73** use distributed, redundant storage for VM data
b5266e9f
DM
74
75* Reduce downtime
8c1189b6
FG
76** rapidly accessible administrators (24/7)
77** availability of spare parts (other nodes in a {pve} cluster)
78** automatic error detection (provided by `ha-manager`)
79** automatic failover (provided by `ha-manager`)
b5266e9f 80
5771d9b0 81Virtualization environments like {pve} make it much easier to reach
8c1189b6 82high availability because they remove the ``hardware'' dependency. They
04bde502
DM
83also support to setup and use redundant storage and network
84devices. So if one host fail, you can simply start those services on
43da8322
DM
85another host within your cluster.
86
8c1189b6 87Even better, {pve} provides a software stack called `ha-manager`,
43da8322
DM
88which can do that automatically for you. It is able to automatically
89detect errors and do automatic failover.
90
8c1189b6 91{pve} `ha-manager` works like an ``automated'' administrator. First, you
43da8322 92configure what resources (VMs, containers, ...) it should
8c1189b6
FG
93manage. `ha-manager` then observes correct functionality, and handles
94service failover to another node in case of errors. `ha-manager` can
43da8322
DM
95also handle normal user requests which may start, stop, relocate and
96migrate a service.
04bde502
DM
97
98But high availability comes at a price. High quality components are
99more expensive, and making them redundant duplicates the costs at
100least. Additional spare parts increase costs further. So you should
101carefully calculate the benefits, and compare with those additional
102costs.
103
104TIP: Increasing availability from 99% to 99.9% is relatively
105simply. But increasing availability from 99.9999% to 99.99999% is very
8c1189b6 106hard and costly. `ha-manager` has typical error detection and failover
43da8322
DM
107times of about 2 minutes, so you can get no more than 99.999%
108availability.
b5266e9f 109
5bd515d4
DM
110Requirements
111------------
3810ae1e 112
5bd515d4 113* at least three cluster nodes (to get reliable quorum)
43da8322 114
5bd515d4 115* shared storage for VMs and containers
43da8322 116
5bd515d4 117* hardware redundancy (everywhere)
3810ae1e 118
5bd515d4 119* hardware watchdog - if not available we fall back to the
8c1189b6 120 linux kernel software watchdog (`softdog`)
3810ae1e 121
5bd515d4 122* optional hardware fencing devices
3810ae1e 123
3810ae1e 124
5bd515d4
DM
125Resources
126---------
127
8c1189b6
FG
128We call the primary management unit handled by `ha-manager` a
129resource. A resource (also called ``service'') is uniquely
5bd515d4 130identified by a service ID (SID), which consists of the resource type
8c1189b6
FG
131and an type specific ID, e.g.: `vm:100`. That example would be a
132resource of type `vm` (virtual machine) with the ID 100.
5bd515d4
DM
133
134For now we have two important resources types - virtual machines and
135containers. One basic idea here is that we can bundle related software
136into such VM or container, so there is no need to compose one big
8c1189b6 137service from other services, like it was done with `rgmanager`. In
5bd515d4 138general, a HA enabled resource should not depend on other resources.
3810ae1e 139
22653ac8 140
2b52e195 141How It Works
22653ac8
DM
142------------
143
3810ae1e
TL
144This section provides an in detail description of the {PVE} HA-manager
145internals. It describes how the CRM and the LRM work together.
146
147To provide High Availability two daemons run on each node:
148
8c1189b6 149`pve-ha-lrm`::
3810ae1e
TL
150
151The local resource manager (LRM), it controls the services running on
152the local node.
153It reads the requested states for its services from the current manager
154status file and executes the respective commands.
155
8c1189b6 156`pve-ha-crm`::
3810ae1e
TL
157
158The cluster resource manager (CRM), it controls the cluster wide
2af6af05 159actions of the services, processes the LRM results and includes the state
3810ae1e
TL
160machine which controls the state of each service.
161
162.Locks in the LRM & CRM
163[NOTE]
164Locks are provided by our distributed configuration file system (pmxcfs).
5771d9b0
TL
165They are used to guarantee that each LRM is active once and working. As a
166LRM only executes actions when it holds its lock we can mark a failed node
167as fenced if we can acquire its lock. This lets us then recover any failed
5eba0743 168HA services securely without any interference from the now unknown failed node.
3810ae1e
TL
169This all gets supervised by the CRM which holds currently the manager master
170lock.
171
172Local Resource Manager
173~~~~~~~~~~~~~~~~~~~~~~
174
8c1189b6 175The local resource manager (`pve-ha-lrm`) is started as a daemon on
3810ae1e
TL
176boot and waits until the HA cluster is quorate and thus cluster wide
177locks are working.
178
179It can be in three states:
180
e1ea726a
FG
181*wait for agent lock*::
182
183The LRM waits for our exclusive lock. This is also used as idle state if no
184service is configured.
185
186*active*::
187
188The LRM holds its exclusive lock and has services configured.
189
190*lost agent lock*::
191
192The LRM lost its lock, this means a failure happened and quorum was lost.
3810ae1e
TL
193
194After the LRM gets in the active state it reads the manager status
8c1189b6 195file in `/etc/pve/ha/manager_status` and determines the commands it
2af6af05 196has to execute for the services it owns.
3810ae1e 197For each command a worker gets started, this workers are running in
5eba0743 198parallel and are limited to at most 4 by default. This default setting
8c1189b6 199may be changed through the datacenter configuration key `max_worker`.
2af6af05
TL
200When finished the worker process gets collected and its result saved for
201the CRM.
3810ae1e 202
5eba0743 203.Maximum Concurrent Worker Adjustment Tips
3810ae1e 204[NOTE]
5eba0743 205The default value of at most 4 concurrent workers may be unsuited for
3810ae1e
TL
206a specific setup. For example may 4 live migrations happen at the same
207time, which can lead to network congestions with slower networks and/or
208big (memory wise) services. Ensure that also in the worst case no congestion
8c1189b6 209happens and lower the `max_worker` value if needed. In the contrary, if you
3810ae1e
TL
210have a particularly powerful high end setup you may also want to increase it.
211
212Each command requested by the CRM is uniquely identifiable by an UID, when
213the worker finished its result will be processed and written in the LRM
8c1189b6 214status file `/etc/pve/nodes/<nodename>/lrm_status`. There the CRM may collect
3810ae1e
TL
215it and let its state machine - respective the commands output - act on it.
216
217The actions on each service between CRM and LRM are normally always synced.
218This means that the CRM requests a state uniquely marked by an UID, the LRM
219then executes this action *one time* and writes back the result, also
220identifiable by the same UID. This is needed so that the LRM does not
221executes an outdated command.
8c1189b6 222With the exception of the `stop` and the `error` command,
c9aa5d47 223those two do not depend on the result produced and are executed
3810ae1e
TL
224always in the case of the stopped state and once in the case of
225the error state.
226
227.Read the Logs
228[NOTE]
229The HA Stack logs every action it makes. This helps to understand what
230and also why something happens in the cluster. Here its important to see
231what both daemons, the LRM and the CRM, did. You may use
232`journalctl -u pve-ha-lrm` on the node(s) where the service is and
233the same command for the pve-ha-crm on the node which is the current master.
234
235Cluster Resource Manager
236~~~~~~~~~~~~~~~~~~~~~~~~
22653ac8 237
8c1189b6 238The cluster resource manager (`pve-ha-crm`) starts on each node and
22653ac8
DM
239waits there for the manager lock, which can only be held by one node
240at a time. The node which successfully acquires the manager lock gets
3810ae1e
TL
241promoted to the CRM master.
242
2af6af05 243It can be in three states:
3810ae1e 244
e1ea726a
FG
245*wait for agent lock*::
246
97ae300a 247The CRM waits for our exclusive lock. This is also used as idle state if no
e1ea726a
FG
248service is configured
249
250*active*::
251
97ae300a 252The CRM holds its exclusive lock and has services configured
e1ea726a
FG
253
254*lost agent lock*::
255
97ae300a 256The CRM lost its lock, this means a failure happened and quorum was lost.
3810ae1e
TL
257
258It main task is to manage the services which are configured to be highly
2af6af05 259available and try to always enforce them to the wanted state, e.g.: a
3810ae1e 260enabled service will be started if its not running, if it crashes it will
2af6af05 261be started again. Thus it dictates the LRM the actions it needs to execute.
22653ac8
DM
262
263When an node leaves the cluster quorum, its state changes to unknown.
264If the current CRM then can secure the failed nodes lock, the services
265will be 'stolen' and restarted on another node.
266
267When a cluster member determines that it is no longer in the cluster
268quorum, the LRM waits for a new quorum to form. As long as there is no
269quorum the node cannot reset the watchdog. This will trigger a reboot
2af6af05 270after the watchdog then times out, this happens after 60 seconds.
22653ac8 271
2b52e195 272Configuration
22653ac8
DM
273-------------
274
2af6af05 275The HA stack is well integrated in the Proxmox VE API2. So, for
8c1189b6 276example, HA can be configured via `ha-manager` or the PVE web
22653ac8
DM
277interface, which both provide an easy to use tool.
278
279The resource configuration file can be located at
8c1189b6
FG
280`/etc/pve/ha/resources.cfg` and the group configuration file at
281`/etc/pve/ha/groups.cfg`. Use the provided tools to make changes,
22653ac8
DM
282there shouldn't be any need to edit them manually.
283
3810ae1e
TL
284Node Power Status
285-----------------
286
287If a node needs maintenance you should migrate and or relocate all
288services which are required to run always on another node first.
289After that you can stop the LRM and CRM services. But note that the
290watchdog triggers if you stop it with active services.
291
5771d9b0
TL
292Package Updates
293---------------
294
2af6af05 295When updating the ha-manager you should do one node after the other, never
5771d9b0
TL
296all at once for various reasons. First, while we test our software
297thoughtfully, a bug affecting your specific setup cannot totally be ruled out.
298Upgrading one node after the other and checking the functionality of each node
299after finishing the update helps to recover from an eventual problems, while
300updating all could render you in a broken cluster state and is generally not
301good practice.
302
303Also, the {pve} HA stack uses a request acknowledge protocol to perform
304actions between the cluster and the local resource manager. For restarting,
305the LRM makes a request to the CRM to freeze all its services. This prevents
306that they get touched by the Cluster during the short time the LRM is restarting.
307After that the LRM may safely close the watchdog during a restart.
308Such a restart happens on a update and as already stated a active master
309CRM is needed to acknowledge the requests from the LRM, if this is not the case
310the update process can be too long which, in the worst case, may result in
311a watchdog reset.
312
2af6af05 313
3810ae1e
TL
314Fencing
315-------
316
5eba0743 317What is Fencing
3810ae1e
TL
318~~~~~~~~~~~~~~~
319
320Fencing secures that on a node failure the dangerous node gets will be rendered
321unable to do any damage and that no resource runs twice when it gets recovered
5771d9b0
TL
322from the failed node. This is a really important task and one of the base
323principles to make a system Highly Available.
324
325If a node would not get fenced it would be in an unknown state where it may
326have still access to shared resources, this is really dangerous!
327Imagine that every network but the storage one broke, now while not
328reachable from the public network the VM still runs and writes on the shared
329storage. If we would not fence the node and just start up this VM on another
330Node we would get dangerous race conditions, atomicity violations the whole VM
331could be rendered unusable. The recovery could also simply fail if the storage
332protects from multiple mounts and thus defeat the purpose of HA.
333
334How {pve} Fences
335~~~~~~~~~~~~~~~~~
336
337There are different methods to fence a node, for example fence devices which
338cut off the power from the node or disable their communication completely.
339
340Those are often quite expensive and bring additional critical components in
341a system, because if they fail you cannot recover any service.
342
343We thus wanted to integrate a simpler method in the HA Manager first, namely
344self fencing with watchdogs.
345
346Watchdogs are widely used in critical and dependable systems since the
347beginning of micro controllers, they are often independent and simple
348integrated circuit which programs can use to watch them. After opening they need to
349report periodically. If, for whatever reason, a program becomes unable to do
350so the watchdogs triggers a reset of the whole server.
351
352Server motherboards often already include such hardware watchdogs, these need
353to be configured. If no watchdog is available or configured we fall back to the
354Linux Kernel softdog while still reliable it is not independent of the servers
355Hardware and thus has a lower reliability then a hardware watchdog.
3810ae1e
TL
356
357Configure Hardware Watchdog
358~~~~~~~~~~~~~~~~~~~~~~~~~~~
359By default all watchdog modules are blocked for security reasons as they are
360like a loaded gun if not correctly initialized.
c9aa5d47 361If you have a hardware watchdog available remove its kernel module from the
8c1189b6 362blacklist, load it with insmod and restart the `watchdog-mux` service or reboot
c9aa5d47 363the node.
3810ae1e 364
2957ef80
TL
365Recover Fenced Services
366~~~~~~~~~~~~~~~~~~~~~~~
367
368After a node failed and its fencing was successful we start to recover services
369to other available nodes and restart them there so that they can provide service
370again.
371
372The selection of the node on which the services gets recovered is influenced
373by the users group settings, the currently active nodes and their respective
374active service count.
375First we build a set out of the intersection between user selected nodes and
376available nodes. Then the subset with the highest priority of those nodes
377gets chosen as possible nodes for recovery. We select the node with the
378currently lowest active service count as a new node for the service.
379That minimizes the possibility of an overload, which else could cause an
380unresponsive node and as a result a chain reaction of node failures in the
381cluster.
382
2b52e195 383Groups
22653ac8
DM
384------
385
386A group is a collection of cluster nodes which a service may be bound to.
387
2b52e195 388Group Settings
22653ac8
DM
389~~~~~~~~~~~~~~
390
391nodes::
392
c9aa5d47
TL
393List of group node members where a priority can be given to each node.
394A service bound to this group will run on the nodes with the highest priority
395available. If more nodes are in the highest priority class the services will
396get distributed to those node if not already there. The priorities have a
397relative meaning only.
22653ac8
DM
398
399restricted::
400
5eba0743 401Resources bound to this group may only run on nodes defined by the
22653ac8
DM
402group. If no group node member is available the resource will be
403placed in the stopped state.
404
405nofailback::
406
5eba0743 407The resource won't automatically fail back when a more preferred node
22653ac8
DM
408(re)joins the cluster.
409
410
a3189ad1
TL
411Start Failure Policy
412---------------------
413
414The start failure policy comes in effect if a service failed to start on a
415node once ore more times. It can be used to configure how often a restart
416should be triggered on the same node and how often a service should be
417relocated so that it gets a try to be started on another node.
418The aim of this policy is to circumvent temporary unavailability of shared
419resources on a specific node. For example, if a shared storage isn't available
420on a quorate node anymore, e.g. network problems, but still on other nodes,
421the relocate policy allows then that the service gets started nonetheless.
422
423There are two service start recover policy settings which can be configured
22653ac8
DM
424specific for each resource.
425
426max_restart::
427
5eba0743 428Maximum number of tries to restart an failed service on the actual
22653ac8
DM
429node. The default is set to one.
430
431max_relocate::
432
5eba0743 433Maximum number of tries to relocate the service to a different node.
22653ac8
DM
434A relocate only happens after the max_restart value is exceeded on the
435actual node. The default is set to one.
436
0abc65b0 437NOTE: The relocate count state will only reset to zero when the
22653ac8
DM
438service had at least one successful start. That means if a service is
439re-enabled without fixing the error only the restart policy gets
440repeated.
441
2b52e195 442Error Recovery
22653ac8
DM
443--------------
444
445If after all tries the service state could not be recovered it gets
446placed in an error state. In this state the service won't get touched
447by the HA stack anymore. To recover from this state you should follow
448these steps:
449
5eba0743 450* bring the resource back into a safe and consistent state (e.g.,
22653ac8
DM
451killing its process)
452
453* disable the ha resource to place it in an stopped state
454
455* fix the error which led to this failures
456
457* *after* you fixed all errors you may enable the service again
458
459
2b52e195 460Service Operations
22653ac8
DM
461------------------
462
463This are how the basic user-initiated service operations (via
8c1189b6 464`ha-manager`) work.
22653ac8
DM
465
466enable::
467
5eba0743 468The service will be started by the LRM if not already running.
22653ac8
DM
469
470disable::
471
5eba0743 472The service will be stopped by the LRM if running.
22653ac8
DM
473
474migrate/relocate::
475
5eba0743 476The service will be relocated (live) to another node.
22653ac8
DM
477
478remove::
479
5eba0743 480The service will be removed from the HA managed resource list. Its
22653ac8
DM
481current state will not be touched.
482
483start/stop::
484
8c1189b6
FG
485`start` and `stop` commands can be issued to the resource specific tools
486(like `qm` or `pct`), they will forward the request to the
487`ha-manager` which then will execute the action and set the resulting
22653ac8
DM
488service state (enabled, disabled).
489
490
2b52e195 491Service States
22653ac8
DM
492--------------
493
494stopped::
495
c9aa5d47
TL
496Service is stopped (confirmed by LRM), if detected running it will get stopped
497again.
22653ac8
DM
498
499request_stop::
500
501Service should be stopped. Waiting for confirmation from LRM.
502
503started::
504
505Service is active an LRM should start it ASAP if not already running.
c9aa5d47 506If the Service fails and is detected to be not running the LRM restarts it.
22653ac8
DM
507
508fence::
509
510Wait for node fencing (service node is not inside quorate cluster
511partition).
c9aa5d47
TL
512As soon as node gets fenced successfully the service will be recovered to
513another node, if possible.
22653ac8
DM
514
515freeze::
516
517Do not touch the service state. We use this state while we reboot a
518node, or when we restart the LRM daemon.
519
520migrate::
521
522Migrate service (live) to other node.
523
524error::
525
526Service disabled because of LRM errors. Needs manual intervention.
527
528
529ifdef::manvolnum[]
530include::pve-copyright.adoc[]
531endif::manvolnum[]
532