root / doc / hooks.rst @ 7faf5110
History | View | Annotate | Download (15 kB)
1 |
Ganeti customisation using hooks |
---|---|
2 |
================================ |
3 |
|
4 |
Documents ganeti version 2.0 |
5 |
|
6 |
.. contents:: |
7 |
|
8 |
Introduction |
9 |
------------ |
10 |
|
11 |
|
12 |
In order to allow customisation of operations, ganeti runs scripts |
13 |
under ``/etc/ganeti/hooks`` based on certain rules. |
14 |
|
15 |
|
16 |
This is similar to the ``/etc/network/`` structure present in Debian |
17 |
for network interface handling. |
18 |
|
19 |
Organisation |
20 |
------------ |
21 |
|
22 |
For every operation, two sets of scripts are run: |
23 |
|
24 |
- pre phase (for authorization/checking) |
25 |
- post phase (for logging) |
26 |
|
27 |
Also, for each operation, the scripts are run on one or more nodes, |
28 |
depending on the operation type. |
29 |
|
30 |
Note that, even though we call them scripts, we are actually talking |
31 |
about any executable. |
32 |
|
33 |
*pre* scripts |
34 |
~~~~~~~~~~~~~ |
35 |
|
36 |
The *pre* scripts have a definite target: to check that the operation |
37 |
is allowed given the site-specific constraints. You could have, for |
38 |
example, a rule that says every new instance is required to exists in |
39 |
a database; to implement this, you could write a script that checks |
40 |
the new instance parameters against your database. |
41 |
|
42 |
The objective of these scripts should be their return code (zero or |
43 |
non-zero for success and failure). However, if they modify the |
44 |
environment in any way, they should be idempotent, as failed |
45 |
executions could be restarted and thus the script(s) run again with |
46 |
exactly the same parameters. |
47 |
|
48 |
Note that if a node is unreachable at the time a hooks is run, this |
49 |
will not be interpreted as a deny for the execution. In other words, |
50 |
only an actual error returned from a script will cause abort, and not |
51 |
an unreachable node. |
52 |
|
53 |
Therefore, if you want to guarantee that a hook script is run and |
54 |
denies an action, it's best to put it on the master node. |
55 |
|
56 |
*post* scripts |
57 |
~~~~~~~~~~~~~~ |
58 |
|
59 |
These scripts should do whatever you need as a reaction to the |
60 |
completion of an operation. Their return code is not checked (but |
61 |
logged), and they should not depend on the fact that the *pre* scripts |
62 |
have been run. |
63 |
|
64 |
Naming |
65 |
~~~~~~ |
66 |
|
67 |
The allowed names for the scripts consist of (similar to *run-parts* ) |
68 |
upper and lower case, digits, underscores and hyphens. In other words, |
69 |
the regexp ``^[a-zA-Z0-9_-]+$``. Also, non-executable scripts will be |
70 |
ignored. |
71 |
|
72 |
|
73 |
Order of execution |
74 |
~~~~~~~~~~~~~~~~~~ |
75 |
|
76 |
On a single node, the scripts in a directory are run in lexicographic |
77 |
order (more exactly, the python string comparison order). It is |
78 |
advisable to implement the usual *NN-name* convention where *NN* is a |
79 |
two digit number. |
80 |
|
81 |
For an operation whose hooks are run on multiple nodes, there is no |
82 |
specific ordering of nodes with regard to hooks execution; you should |
83 |
assume that the scripts are run in parallel on the target nodes |
84 |
(keeping on each node the above specified ordering). If you need any |
85 |
kind of inter-node synchronisation, you have to implement it yourself |
86 |
in the scripts. |
87 |
|
88 |
Execution environment |
89 |
~~~~~~~~~~~~~~~~~~~~~ |
90 |
|
91 |
The scripts will be run as follows: |
92 |
|
93 |
- no command line arguments |
94 |
|
95 |
- no controlling *tty* |
96 |
|
97 |
- stdin is actually */dev/null* |
98 |
|
99 |
- stdout and stderr are directed to files |
100 |
|
101 |
- PATH is reset to ``/sbin:/bin:/usr/sbin:/usr/bin`` |
102 |
|
103 |
- the environment is cleared, and only ganeti-specific variables will |
104 |
be left |
105 |
|
106 |
|
107 |
All information about the cluster is passed using environment |
108 |
variables. Different operations will have sligthly different |
109 |
environments, but most of the variables are common. |
110 |
|
111 |
Operation list |
112 |
-------------- |
113 |
|
114 |
Node operations |
115 |
~~~~~~~~~~~~~~~ |
116 |
|
117 |
OP_ADD_NODE |
118 |
+++++++++++ |
119 |
|
120 |
Adds a node to the cluster. |
121 |
|
122 |
:directory: node-add |
123 |
:env. vars: NODE_NAME, NODE_PIP, NODE_SIP |
124 |
:pre-execution: all existing nodes |
125 |
:post-execution: all nodes plus the new node |
126 |
|
127 |
|
128 |
OP_REMOVE_NODE |
129 |
++++++++++++++ |
130 |
|
131 |
Removes a node from the cluster. On the removed node the hooks are |
132 |
called during the execution of the operation and not after its |
133 |
completion. |
134 |
|
135 |
:directory: node-remove |
136 |
:env. vars: NODE_NAME |
137 |
:pre-execution: all existing nodes except the removed node |
138 |
:post-execution: all existing nodes |
139 |
|
140 |
OP_NODE_SET_PARAMS |
141 |
++++++++++++++++++ |
142 |
|
143 |
Changes a node's parameters. |
144 |
|
145 |
:directory: node-modify |
146 |
:env. vars: MASTER_CANDIDATE, OFFLINE, DRAINED |
147 |
:pre-execution: master node, the target node |
148 |
:post-execution: master node, the target node |
149 |
|
150 |
OP_NODE_EVACUATE |
151 |
++++++++++++++++ |
152 |
|
153 |
Relocate secondary instances from a node. |
154 |
|
155 |
:directory: node-evacuate |
156 |
:env. vars: NEW_SECONDARY, NODE_NAME |
157 |
:pre-execution: master node, target node |
158 |
:post-execution: master node, target node |
159 |
|
160 |
OP_NODE_MIGRATE |
161 |
++++++++++++++++ |
162 |
|
163 |
Relocate secondary instances from a node. |
164 |
|
165 |
:directory: node-migrate |
166 |
:env. vars: NODE_NAME |
167 |
:pre-execution: master node |
168 |
:post-execution: master node |
169 |
|
170 |
|
171 |
Instance operations |
172 |
~~~~~~~~~~~~~~~~~~~ |
173 |
|
174 |
All instance operations take at least the following variables: |
175 |
INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, |
176 |
INSTANCE_OS_TYPE, INSTANCE_DISK_TEMPLATE, INSTANCE_MEMORY, |
177 |
INSTANCE_DISK_SIZES, INSTANCE_VCPUS, INSTANCE_NIC_COUNT, |
178 |
INSTANCE_NICn_IP, INSTANCE_NICn_BRIDGE, INSTANCE_NICn_MAC, |
179 |
INSTANCE_DISK_COUNT, INSTANCE_DISKn_SIZE, INSTANCE_DISKn_MODE. |
180 |
|
181 |
The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the |
182 |
properties of the *n* -th NIC and disk, and are zero-indexed. |
183 |
|
184 |
|
185 |
OP_INSTANCE_ADD |
186 |
+++++++++++++++ |
187 |
|
188 |
Creates a new instance. |
189 |
|
190 |
:directory: instance-add |
191 |
:env. vars: ADD_MODE, SRC_NODE, SRC_PATH, SRC_IMAGES |
192 |
:pre-execution: master node, primary and secondary nodes |
193 |
:post-execution: master node, primary and secondary nodes |
194 |
|
195 |
OP_INSTANCE_REINSTALL |
196 |
+++++++++++++++++++++ |
197 |
|
198 |
Reinstalls an instance. |
199 |
|
200 |
:directory: instance-reinstall |
201 |
:env. vars: only the standard instance vars |
202 |
:pre-execution: master node, primary and secondary nodes |
203 |
:post-execution: master node, primary and secondary nodes |
204 |
|
205 |
OP_BACKUP_EXPORT |
206 |
++++++++++++++++ |
207 |
|
208 |
Exports the instance. |
209 |
|
210 |
|
211 |
:directory: instance-export |
212 |
:env. vars: EXPORT_NODE, EXPORT_DO_SHUTDOWN |
213 |
:pre-execution: master node, primary and secondary nodes |
214 |
:post-execution: master node, primary and secondary nodes |
215 |
|
216 |
OP_INSTANCE_START |
217 |
+++++++++++++++++ |
218 |
|
219 |
Starts an instance. |
220 |
|
221 |
:directory: instance-start |
222 |
:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, FORCE |
223 |
:pre-execution: master node, primary and secondary nodes |
224 |
:post-execution: master node, primary and secondary nodes |
225 |
|
226 |
OP_INSTANCE_SHUTDOWN |
227 |
++++++++++++++++++++ |
228 |
|
229 |
Stops an instance. |
230 |
|
231 |
:directory: instance-stop |
232 |
:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES |
233 |
:pre-execution: master node, primary and secondary nodes |
234 |
:post-execution: master node, primary and secondary nodes |
235 |
|
236 |
OP_INSTANCE_REBOOT |
237 |
++++++++++++++++++ |
238 |
|
239 |
Reboots an instance. |
240 |
|
241 |
:directory: instance-reboot |
242 |
:env. vars: IGNORE_SECONDARIES, REBOOT_TYPE |
243 |
:pre-execution: master node, primary and secondary nodes |
244 |
:post-execution: master node, primary and secondary nodes |
245 |
|
246 |
OP_INSTANCE_MODIFY |
247 |
++++++++++++++++++ |
248 |
|
249 |
Modifies the instance parameters. |
250 |
|
251 |
:directory: instance-modify |
252 |
:env. vars: INSTANCE_NAME, MEM_SIZE, VCPUS, INSTANCE_IP |
253 |
:pre-execution: master node, primary and secondary nodes |
254 |
:post-execution: master node, primary and secondary nodes |
255 |
|
256 |
OP_INSTANCE_FAILOVER |
257 |
++++++++++++++++++++ |
258 |
|
259 |
Failovers an instance. |
260 |
|
261 |
:directory: instance-failover |
262 |
:env. vars: IGNORE_CONSISTENCY |
263 |
:pre-execution: master node, secondary node |
264 |
:post-execution: master node, secondary node |
265 |
|
266 |
OP_INSTANCE_MIGRATE |
267 |
++++++++++++++++++++ |
268 |
|
269 |
Migrates an instance. |
270 |
|
271 |
:directory: instance-migrate |
272 |
:env. vars: INSTANCE_MIGRATE_LIVE, INSTANCE_MIGRATE_CLEANUP |
273 |
:pre-execution: master node, secondary node |
274 |
:post-execution: master node, secondary node |
275 |
|
276 |
|
277 |
OP_INSTANCE_REMOVE |
278 |
++++++++++++++++++ |
279 |
|
280 |
Remove an instance. |
281 |
|
282 |
:directory: instance-remove |
283 |
:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES |
284 |
:pre-execution: master node |
285 |
:post-execution: master node |
286 |
|
287 |
OP_INSTANCE_REPLACE_DISKS |
288 |
+++++++++++++++++++++++++ |
289 |
|
290 |
Replace an instance's disks. |
291 |
|
292 |
:directory: mirror-replace |
293 |
:env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY |
294 |
:pre-execution: master node, primary and secondary nodes |
295 |
:post-execution: master node, primary and secondary nodes |
296 |
|
297 |
OP_INSTANCE_GROW_DISK |
298 |
+++++++++++++++++++++ |
299 |
|
300 |
Grows the disk of an instance. |
301 |
|
302 |
:directory: disk-grow |
303 |
:env. vars: DISK, AMOUNT |
304 |
:pre-execution: master node, primary node |
305 |
:post-execution: master node, primary node |
306 |
|
307 |
OP_INSTANCE_RENAME |
308 |
++++++++++++++++++ |
309 |
|
310 |
Renames an instance. |
311 |
|
312 |
:directory: instance-rename |
313 |
:env. vars: INSTANCE_NEW_NAME |
314 |
:pre-execution: master node, primary and secondary nodes |
315 |
:post-execution: master node, primary and secondary nodes |
316 |
|
317 |
OP_INSTANCE_MOVE |
318 |
++++++++++++++++ |
319 |
|
320 |
Move an instance by data-copying. |
321 |
|
322 |
:directory: instance-move |
323 |
:env. vars: TARGET_NODE |
324 |
:pre-execution: master node, primary and target nodes |
325 |
:post-execution: master node, primary and target nodes |
326 |
|
327 |
OP_INSTANCE_RECREATE_DISKS |
328 |
++++++++++++++++++++++++++ |
329 |
|
330 |
Recreate an instance's missing disks. |
331 |
|
332 |
:directory: instance-recreate-disks |
333 |
:env. vars: only the standard instance vars |
334 |
:pre-execution: master node, primary and secondary nodes |
335 |
:post-execution: master node, primary and secondary nodes |
336 |
|
337 |
OP_INSTANCE_REPLACE_DISKS |
338 |
+++++++++++++++++++++++++ |
339 |
|
340 |
Replace the disks of an instance. |
341 |
|
342 |
:directory: mirrors-replace |
343 |
:env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY |
344 |
:pre-execution: master node, primary and new secondary nodes |
345 |
:post-execution: master node, primary and new secondary nodes |
346 |
|
347 |
|
348 |
Cluster operations |
349 |
~~~~~~~~~~~~~~~~~~ |
350 |
|
351 |
OP_POST_INIT_CLUSTER |
352 |
++++++++++++++++++++ |
353 |
|
354 |
This hook is called via a special "empty" LU right after cluster |
355 |
initialization. |
356 |
|
357 |
:directory: cluster-init |
358 |
:env. vars: none |
359 |
:pre-execution: none |
360 |
:post-execution: master node |
361 |
|
362 |
OP_DESTROY_CLUSTER |
363 |
++++++++++++++++++ |
364 |
|
365 |
The post phase of this hook is called during the execution of destroy |
366 |
operation and not after its completion. |
367 |
|
368 |
:directory: cluster-destroy |
369 |
:env. vars: none |
370 |
:pre-execution: none |
371 |
:post-execution: master node |
372 |
|
373 |
OP_CLUSTER_VERIFY |
374 |
+++++++++++++++++ |
375 |
|
376 |
Verifies the cluster status. This is a special LU with regard to |
377 |
hooks, as the result of the opcode will be combined with the result of |
378 |
post-execution hooks, in order to allow administrators to enhance the |
379 |
cluster verification procedure. |
380 |
|
381 |
:directory: cluster-verify |
382 |
:env. vars: CLUSTER, MASTER, CLUSTER_TAGS, NODE_TAGS_<name> |
383 |
:pre-execution: none |
384 |
:post-execution: all nodes |
385 |
|
386 |
OP_CLUSTER_RENAME |
387 |
+++++++++++++++++ |
388 |
|
389 |
Renames the cluster. |
390 |
|
391 |
:directory: cluster-rename |
392 |
:env. vars: NEW_NAME |
393 |
:pre-execution: master-node |
394 |
:post-execution: master-node |
395 |
|
396 |
OP_CLUSTER_SET_PARAMS |
397 |
+++++++++++++++++++++ |
398 |
|
399 |
Modifies the cluster parameters. |
400 |
|
401 |
:directory: cluster-modify |
402 |
:env. vars: NEW_VG_NAME |
403 |
:pre-execution: master node |
404 |
:post-execution: master node |
405 |
|
406 |
|
407 |
Obsolete operations |
408 |
~~~~~~~~~~~~~~~~~~~ |
409 |
|
410 |
The following operations are no longer present or don't execute hooks |
411 |
anymore in Ganeti 2.0: |
412 |
|
413 |
- OP_INIT_CLUSTER |
414 |
- OP_MASTER_FAILOVER |
415 |
- OP_INSTANCE_ADD_MDDRBD |
416 |
- OP_INSTANCE_REMOVE_MDDRBD |
417 |
|
418 |
|
419 |
Environment variables |
420 |
--------------------- |
421 |
|
422 |
Note that all variables listed here are actually prefixed with |
423 |
*GANETI_* in order to provide a clear namespace. |
424 |
|
425 |
Common variables |
426 |
~~~~~~~~~~~~~~~~ |
427 |
|
428 |
This is the list of environment variables supported by all operations: |
429 |
|
430 |
HOOKS_VERSION |
431 |
Documents the hooks interface version. In case this doesnt match |
432 |
what the script expects, it should not run. The documents conforms |
433 |
to the version 2. |
434 |
|
435 |
HOOKS_PHASE |
436 |
One of *PRE* or *POST* denoting which phase are we in. |
437 |
|
438 |
CLUSTER |
439 |
The cluster name. |
440 |
|
441 |
MASTER |
442 |
The master node. |
443 |
|
444 |
OP_CODE |
445 |
One of the *OP_* values from the list of operations. |
446 |
|
447 |
OBJECT_TYPE |
448 |
One of ``INSTANCE``, ``NODE``, ``CLUSTER``. |
449 |
|
450 |
DATA_DIR |
451 |
The path to the Ganeti configuration directory (to read, for |
452 |
example, the *ssconf* files). |
453 |
|
454 |
|
455 |
Specialised variables |
456 |
~~~~~~~~~~~~~~~~~~~~~ |
457 |
|
458 |
This is the list of variables which are specific to one or more |
459 |
operations. |
460 |
|
461 |
INSTANCE_NAME |
462 |
The name of the instance which is the target of the operation. |
463 |
|
464 |
INSTANCE_DISK_TEMPLATE |
465 |
The disk type for the instance. |
466 |
|
467 |
INSTANCE_DISK_COUNT |
468 |
The number of disks for the instance. |
469 |
|
470 |
INSTANCE_DISKn_SIZE |
471 |
The size of disk *n* for the instance. |
472 |
|
473 |
INSTANCE_DISKn_MODE |
474 |
Either *rw* for a read-write disk or *ro* for a read-only one. |
475 |
|
476 |
INSTANCE_NIC_COUNT |
477 |
The number of NICs for the instance. |
478 |
|
479 |
INSTANCE_NICn_BRIDGE |
480 |
The bridge to which the *n* -th NIC of the instance is attached. |
481 |
|
482 |
INSTANCE_NICn_IP |
483 |
The IP (if any) of the *n* -th NIC of the instance. |
484 |
|
485 |
INSTANCE_NICn_MAC |
486 |
The MAC address of the *n* -th NIC of the instance. |
487 |
|
488 |
INSTANCE_OS_TYPE |
489 |
The name of the instance OS. |
490 |
|
491 |
INSTANCE_PRIMARY |
492 |
The name of the node which is the primary for the instance. |
493 |
|
494 |
INSTANCE_SECONDARIES |
495 |
Space-separated list of secondary nodes for the instance. |
496 |
|
497 |
INSTANCE_MEMORY |
498 |
The memory size (in MiBs) of the instance. |
499 |
|
500 |
INSTANCE_VCPUS |
501 |
The number of virtual CPUs for the instance. |
502 |
|
503 |
INSTANCE_STATUS |
504 |
The run status of the instance. |
505 |
|
506 |
NODE_NAME |
507 |
The target node of this operation (not the node on which the hook |
508 |
runs). |
509 |
|
510 |
NODE_PIP |
511 |
The primary IP of the target node (the one over which inter-node |
512 |
communication is done). |
513 |
|
514 |
NODE_SIP |
515 |
The secondary IP of the target node (the one over which drbd |
516 |
replication is done). This can be equal to the primary ip, in case |
517 |
the cluster is not dual-homed. |
518 |
|
519 |
FORCE |
520 |
This is provided by some operations when the user gave this flag. |
521 |
|
522 |
IGNORE_CONSISTENCY |
523 |
The user has specified this flag. It is used when failing over |
524 |
instances in case the primary node is down. |
525 |
|
526 |
ADD_MODE |
527 |
The mode of the instance create: either *create* for create from |
528 |
scratch or *import* for restoring from an exported image. |
529 |
|
530 |
SRC_NODE, SRC_PATH, SRC_IMAGE |
531 |
In case the instance has been added by import, these variables are |
532 |
defined and point to the source node, source path (the directory |
533 |
containing the image and the config file) and the source disk image |
534 |
file. |
535 |
|
536 |
NEW_SECONDARY |
537 |
The name of the node on which the new mirror component is being |
538 |
added. This can be the name of the current secondary, if the new |
539 |
mirror is on the same secondary. |
540 |
|
541 |
OLD_SECONDARY |
542 |
The name of the old secondary in the replace-disks command Note that |
543 |
this can be equal to the new secondary if the secondary node hasn't |
544 |
actually changed. |
545 |
|
546 |
EXPORT_NODE |
547 |
The node on which the exported image of the instance was done. |
548 |
|
549 |
EXPORT_DO_SHUTDOWN |
550 |
This variable tells if the instance has been shutdown or not while |
551 |
doing the export. In the "was shutdown" case, it's likely that the |
552 |
filesystem is consistent, whereas in the "did not shutdown" case, |
553 |
the filesystem would need a check (journal replay or full fsck) in |
554 |
order to guarantee consistency. |
555 |
|
556 |
CLUSTER_TAGS |
557 |
The list of cluster tags, space separated. |
558 |
|
559 |
NODE_TAGS_<name> |
560 |
The list of tags for node *<name>*, space separated. |
561 |
|
562 |
Examples |
563 |
-------- |
564 |
|
565 |
The startup of an instance will pass this environment to the hook |
566 |
script:: |
567 |
|
568 |
GANETI_CLUSTER=cluster1.example.com |
569 |
GANETI_DATA_DIR=/var/lib/ganeti |
570 |
GANETI_FORCE=False |
571 |
GANETI_HOOKS_PATH=instance-start |
572 |
GANETI_HOOKS_PHASE=post |
573 |
GANETI_HOOKS_VERSION=2 |
574 |
GANETI_INSTANCE_DISK0_MODE=rw |
575 |
GANETI_INSTANCE_DISK0_SIZE=128 |
576 |
GANETI_INSTANCE_DISK_COUNT=1 |
577 |
GANETI_INSTANCE_DISK_TEMPLATE=drbd |
578 |
GANETI_INSTANCE_MEMORY=128 |
579 |
GANETI_INSTANCE_NAME=instance2.example.com |
580 |
GANETI_INSTANCE_NIC0_BRIDGE=xen-br0 |
581 |
GANETI_INSTANCE_NIC0_IP= |
582 |
GANETI_INSTANCE_NIC0_MAC=aa:00:00:a5:91:58 |
583 |
GANETI_INSTANCE_NIC_COUNT=1 |
584 |
GANETI_INSTANCE_OS_TYPE=debootstrap |
585 |
GANETI_INSTANCE_PRIMARY=node3.example.com |
586 |
GANETI_INSTANCE_SECONDARIES=node5.example.com |
587 |
GANETI_INSTANCE_STATUS=down |
588 |
GANETI_INSTANCE_VCPUS=1 |
589 |
GANETI_MASTER=node1.example.com |
590 |
GANETI_OBJECT_TYPE=INSTANCE |
591 |
GANETI_OP_CODE=OP_INSTANCE_STARTUP |
592 |
GANETI_OP_TARGET=instance2.example.com |
593 |
|
594 |
.. vim: set textwidth=72 : |