1 Ganeti customisation using hooks
2 ================================
4 Documents ganeti version 2.0
12 In order to allow customisation of operations, ganeti runs scripts
13 under ``/etc/ganeti/hooks`` based on certain rules.
16 This is similar to the ``/etc/network/`` structure present in Debian
17 for network interface handling.
22 For every operation, two sets of scripts are run:
24 - pre phase (for authorization/checking)
25 - post phase (for logging)
27 Also, for each operation, the scripts are run on one or more nodes,
28 depending on the operation type.
30 Note that, even though we call them scripts, we are actually talking
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.
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.
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
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.
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
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
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
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
91 The scripts will be run as follows:
93 - no command line arguments
95 - no controlling *tty*
97 - stdin is actually */dev/null*
99 - stdout and stderr are directed to files
101 - PATH is reset to ``/sbin:/bin:/usr/sbin:/usr/bin``
103 - the environment is cleared, and only ganeti-specific variables will
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.
120 Adds a node to the cluster.
123 :env. vars: NODE_NAME, NODE_PIP, NODE_SIP
124 :pre-execution: all existing nodes
125 :post-execution: all nodes plus the new node
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
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
143 Changes a node's parameters.
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
153 Relocate secondary instances from a node.
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
163 Relocate secondary instances from a node.
165 :directory: node-migrate
166 :env. vars: NODE_NAME
167 :pre-execution: master node
168 :post-execution: master node
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.
181 The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the
182 properties of the *n* -th NIC and disk, and are zero-indexed.
188 Creates a new instance.
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
195 OP_INSTANCE_REINSTALL
196 +++++++++++++++++++++
198 Reinstalls an instance.
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
208 Exports the instance.
210 :directory: instance-export
211 :env. vars: EXPORT_NODE, EXPORT_DO_SHUTDOWN
212 :pre-execution: master node, primary and secondary nodes
213 :post-execution: master node, primary and secondary nodes
220 :directory: instance-start
222 :pre-execution: master node, primary and secondary nodes
223 :post-execution: master node, primary and secondary nodes
230 :directory: instance-stop
231 :env. vars: only the standard instance vars
232 :pre-execution: master node, primary and secondary nodes
233 :post-execution: master node, primary and secondary nodes
240 :directory: instance-reboot
241 :env. vars: IGNORE_SECONDARIES, REBOOT_TYPE
242 :pre-execution: master node, primary and secondary nodes
243 :post-execution: master node, primary and secondary nodes
248 Modifies the instance parameters.
250 :directory: instance-modify
251 :env. vars: only the standard instance vars
252 :pre-execution: master node, primary and secondary nodes
253 :post-execution: master node, primary and secondary nodes
258 Failovers an instance. In the post phase INSTANCE_PRIMARY and
259 INSTANCE_SECONDARIES refer to the nodes that were repectively primary
260 and secondary before failover.
262 :directory: instance-failover
263 :env. vars: IGNORE_CONSISTENCY
264 :pre-execution: master node, secondary node
265 :post-execution: master node, secondary node
270 Migrates an instance. In the post phase INSTANCE_PRIMARY and
271 INSTANCE_SECONDARIES refer to the nodes that were repectively primary
272 and secondary before migration.
274 :directory: instance-migrate
275 :env. vars: MIGRATE_LIVE, MIGRATE_CLEANUP
276 :pre-execution: master node, secondary node
277 :post-execution: master node, secondary node
285 :directory: instance-remove
286 :env. vars: only the standard instance vars
287 :pre-execution: master node
288 :post-execution: master node
290 OP_INSTANCE_REPLACE_DISKS
291 +++++++++++++++++++++++++
293 Replace an instance's disks.
295 :directory: mirror-replace
296 :env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY
297 :pre-execution: master node, primary and secondary nodes
298 :post-execution: master node, primary and secondary nodes
300 OP_INSTANCE_GROW_DISK
301 +++++++++++++++++++++
303 Grows the disk of an instance.
305 :directory: disk-grow
306 :env. vars: DISK, AMOUNT
307 :pre-execution: master node, primary node
308 :post-execution: master node, primary node
315 :directory: instance-rename
316 :env. vars: INSTANCE_NEW_NAME
317 :pre-execution: master node, primary and secondary nodes
318 :post-execution: master node, primary and secondary nodes
323 Move an instance by data-copying.
325 :directory: instance-move
326 :env. vars: TARGET_NODE
327 :pre-execution: master node, primary and target nodes
328 :post-execution: master node, primary and target nodes
330 OP_INSTANCE_RECREATE_DISKS
331 ++++++++++++++++++++++++++
333 Recreate an instance's missing disks.
335 :directory: instance-recreate-disks
336 :env. vars: only the standard instance vars
337 :pre-execution: master node, primary and secondary nodes
338 :post-execution: master node, primary and secondary nodes
340 OP_INSTANCE_REPLACE_DISKS
341 +++++++++++++++++++++++++
343 Replace the disks of an instance.
345 :directory: mirrors-replace
346 :env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY
347 :pre-execution: master node, primary and new secondary nodes
348 :post-execution: master node, primary and new secondary nodes
357 This hook is called via a special "empty" LU right after cluster
360 :directory: cluster-init
363 :post-execution: master node
368 The post phase of this hook is called during the execution of destroy
369 operation and not after its completion.
371 :directory: cluster-destroy
374 :post-execution: master node
379 Verifies the cluster status. This is a special LU with regard to
380 hooks, as the result of the opcode will be combined with the result of
381 post-execution hooks, in order to allow administrators to enhance the
382 cluster verification procedure.
384 :directory: cluster-verify
385 :env. vars: CLUSTER, MASTER, CLUSTER_TAGS, NODE_TAGS_<name>
387 :post-execution: all nodes
394 :directory: cluster-rename
396 :pre-execution: master-node
397 :post-execution: master-node
399 OP_CLUSTER_SET_PARAMS
400 +++++++++++++++++++++
402 Modifies the cluster parameters.
404 :directory: cluster-modify
405 :env. vars: NEW_VG_NAME
406 :pre-execution: master node
407 :post-execution: master node
413 The following operations are no longer present or don't execute hooks
414 anymore in Ganeti 2.0:
418 - OP_INSTANCE_ADD_MDDRBD
419 - OP_INSTANCE_REMOVE_MDDRBD
422 Environment variables
423 ---------------------
425 Note that all variables listed here are actually prefixed with
426 *GANETI_* in order to provide a clear namespace.
431 This is the list of environment variables supported by all operations:
434 Documents the hooks interface version. In case this doesnt match
435 what the script expects, it should not run. The documents conforms
439 One of *PRE* or *POST* denoting which phase are we in.
448 One of the *OP_* values from the list of operations.
451 One of ``INSTANCE``, ``NODE``, ``CLUSTER``.
454 The path to the Ganeti configuration directory (to read, for
455 example, the *ssconf* files).
458 Specialised variables
459 ~~~~~~~~~~~~~~~~~~~~~
461 This is the list of variables which are specific to one or more
465 The name of the instance which is the target of the operation.
467 INSTANCE_DISK_TEMPLATE
468 The disk type for the instance.
471 The number of disks for the instance.
474 The size of disk *n* for the instance.
477 Either *rw* for a read-write disk or *ro* for a read-only one.
480 The number of NICs for the instance.
483 The bridge to which the *n* -th NIC of the instance is attached.
486 The IP (if any) of the *n* -th NIC of the instance.
489 The MAC address of the *n* -th NIC of the instance.
492 The name of the instance OS.
495 The name of the node which is the primary for the instance.
498 Space-separated list of secondary nodes for the instance.
501 The memory size (in MiBs) of the instance.
504 The number of virtual CPUs for the instance.
507 The run status of the instance.
510 The target node of this operation (not the node on which the hook
514 The primary IP of the target node (the one over which inter-node
515 communication is done).
518 The secondary IP of the target node (the one over which drbd
519 replication is done). This can be equal to the primary ip, in case
520 the cluster is not dual-homed.
523 This is provided by some operations when the user gave this flag.
526 The user has specified this flag. It is used when failing over
527 instances in case the primary node is down.
530 The mode of the instance create: either *create* for create from
531 scratch or *import* for restoring from an exported image.
533 SRC_NODE, SRC_PATH, SRC_IMAGE
534 In case the instance has been added by import, these variables are
535 defined and point to the source node, source path (the directory
536 containing the image and the config file) and the source disk image
540 The name of the node on which the new mirror component is being
541 added. This can be the name of the current secondary, if the new
542 mirror is on the same secondary.
545 The name of the old secondary in the replace-disks command Note that
546 this can be equal to the new secondary if the secondary node hasn't
550 The node on which the exported image of the instance was done.
553 This variable tells if the instance has been shutdown or not while
554 doing the export. In the "was shutdown" case, it's likely that the
555 filesystem is consistent, whereas in the "did not shutdown" case,
556 the filesystem would need a check (journal replay or full fsck) in
557 order to guarantee consistency.
560 The list of cluster tags, space separated.
563 The list of tags for node *<name>*, space separated.
568 The startup of an instance will pass this environment to the hook
571 GANETI_CLUSTER=cluster1.example.com
572 GANETI_DATA_DIR=/var/lib/ganeti
574 GANETI_HOOKS_PATH=instance-start
575 GANETI_HOOKS_PHASE=post
576 GANETI_HOOKS_VERSION=2
577 GANETI_INSTANCE_DISK0_MODE=rw
578 GANETI_INSTANCE_DISK0_SIZE=128
579 GANETI_INSTANCE_DISK_COUNT=1
580 GANETI_INSTANCE_DISK_TEMPLATE=drbd
581 GANETI_INSTANCE_MEMORY=128
582 GANETI_INSTANCE_NAME=instance2.example.com
583 GANETI_INSTANCE_NIC0_BRIDGE=xen-br0
584 GANETI_INSTANCE_NIC0_IP=
585 GANETI_INSTANCE_NIC0_MAC=aa:00:00:a5:91:58
586 GANETI_INSTANCE_NIC_COUNT=1
587 GANETI_INSTANCE_OS_TYPE=debootstrap
588 GANETI_INSTANCE_PRIMARY=node3.example.com
589 GANETI_INSTANCE_SECONDARIES=node5.example.com
590 GANETI_INSTANCE_STATUS=down
591 GANETI_INSTANCE_VCPUS=1
592 GANETI_MASTER=node1.example.com
593 GANETI_OBJECT_TYPE=INSTANCE
594 GANETI_OP_CODE=OP_INSTANCE_STARTUP
595 GANETI_OP_TARGET=instance2.example.com
597 .. vim: set textwidth=72 :