code.grnet.gr Git - ganeti-local/blob - doc/hooks.rst

   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.
 132
 133 :directory: node-remove
 134 :env. vars: NODE_NAME
 135 :pre-execution: all existing nodes except the removed node
 136 :post-execution: all existing nodes except the removed node
 137
 138 OP_NODE_SET_PARAMS
 139 ++++++++++++++++++
 140
 141 Changes a node's parameters.
 142
 143 :directory: node-modify
 144 :env. vars: MASTER_CANDIDATE, OFFLINE, DRAINED
 145 :pre-execution: master node, the target node
 146 :post-execution: master node, the target node
 147
 148 OP_NODE_EVACUATE
 149 ++++++++++++++++
 150
 151 Relocate secondary instances from a node.
 152
 153 :directory: node-evacuate
 154 :env. vars: NEW_SECONDARY, NODE_NAME
 155 :pre-execution: master node, target node
 156 :post-execution: master node, target node
 157
 158
 159 Instance operations
 160 ~~~~~~~~~~~~~~~~~~~
 161
 162 All instance operations take at least the following variables:
 163 INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES,
 164 INSTANCE_OS_TYPE, INSTANCE_DISK_TEMPLATE, INSTANCE_MEMORY,
 165 INSTANCE_DISK_SIZES, INSTANCE_VCPUS, INSTANCE_NIC_COUNT,
 166 INSTANCE_NICn_IP, INSTANCE_NICn_BRIDGE, INSTANCE_NICn_MAC,
 167 INSTANCE_DISK_COUNT, INSTANCE_DISKn_SIZE, INSTANCE_DISKn_MODE.
 168
 169 The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the
 170 properties of the *n* -th NIC and disk, and are zero-indexed.
 171
 172
 173 OP_INSTANCE_ADD
 174 +++++++++++++++
 175
 176 Creates a new instance.
 177
 178 :directory: instance-add
 179 :env. vars: ADD_MODE, SRC_NODE, SRC_PATH, SRC_IMAGES
 180 :pre-execution: master node, primary and secondary nodes
 181 :post-execution: master node, primary and secondary nodes
 182
 183 OP_INSTANCE_REINSTALL
 184 +++++++++++++++++++++
 185
 186 Reinstalls an instance.
 187
 188 :directory: instance-reinstall
 189 :env. vars: only the standard instance vars
 190 :pre-execution: master node, primary and secondary nodes
 191 :post-execution: master node, primary and secondary nodes
 192
 193 OP_BACKUP_EXPORT
 194 ++++++++++++++++
 195
 196 Exports the instance.
 197
 198
 199 :directory: instance-export
 200 :env. vars: EXPORT_NODE, EXPORT_DO_SHUTDOWN
 201 :pre-execution: master node, primary and secondary nodes
 202 :post-execution: master node, primary and secondary nodes
 203
 204 OP_INSTANCE_START
 205 +++++++++++++++++
 206
 207 Starts an instance.
 208
 209 :directory: instance-start
 210 :env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, FORCE
 211 :pre-execution: master node, primary and secondary nodes
 212 :post-execution: master node, primary and secondary nodes
 213
 214 OP_INSTANCE_SHUTDOWN
 215 ++++++++++++++++++++
 216
 217 Stops an instance.
 218
 219 :directory: instance-shutdown
 220 :env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES
 221 :pre-execution: master node, primary and secondary nodes
 222 :post-execution: master node, primary and secondary nodes
 223
 224 OP_INSTANCE_REBOOT
 225 ++++++++++++++++++
 226
 227 Reboots an instance.
 228
 229 :directory: instance-reboot
 230 :env. vars: IGNORE_SECONDARIES, REBOOT_TYPE
 231 :pre-execution: master node, primary and secondary nodes
 232 :post-execution: master node, primary and secondary nodes
 233
 234 OP_INSTANCE_MODIFY
 235 ++++++++++++++++++
 236
 237 Modifies the instance parameters.
 238
 239 :directory: instance-modify
 240 :env. vars: INSTANCE_NAME, MEM_SIZE, VCPUS, INSTANCE_IP
 241 :pre-execution: master node, primary and secondary nodes
 242 :post-execution: master node, primary and secondary nodes
 243
 244 OP_INSTANCE_FAILOVER
 245 ++++++++++++++++++++
 246
 247 Failovers an instance.
 248
 249 :directory: instance-failover
 250 :env. vars: IGNORE_CONSISTENCY
 251 :pre-execution: master node, secondary node
 252 :post-execution: master node, secondary node
 253
 254 OP_INSTANCE_MIGRATE
 255 ++++++++++++++++++++
 256
 257 Migrates an instance.
 258
 259 :directory: instance-failover
 260 :env. vars: INSTANCE_MIGRATE_LIVE, INSTANCE_MIGRATE_CLEANUP
 261 :pre-execution: master node, secondary node
 262 :post-execution: master node, secondary node
 263
 264
 265 OP_INSTANCE_REMOVE
 266 ++++++++++++++++++
 267
 268 Remove an instance.
 269
 270 :directory: instance-remove
 271 :env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES
 272 :pre-execution: master node
 273 :post-execution: master node
 274
 275 OP_INSTANCE_REPLACE_DISKS
 276 +++++++++++++++++++++++++
 277
 278 Replace an instance's disks.
 279
 280 :directory: mirror-replace
 281 :env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY
 282 :pre-execution: master node, primary and secondary nodes
 283 :post-execution: master node, primary and secondary nodes
 284
 285 OP_INSTANCE_GROW_DISK
 286 +++++++++++++++++++++
 287
 288 Grows the disk of an instance.
 289
 290 :directory: disk-grow
 291 :env. vars: DISK, AMOUNT
 292 :pre-execution: master node, primary node
 293 :post-execution: master node, primary node
 294
 295 OP_INSTANCE_RENAME
 296 ++++++++++++++++++
 297
 298 Renames an instance.
 299
 300 :directory: instance-rename
 301 :env. vars: INSTANCE_NEW_NAME
 302 :pre-execution: master node, primary and secondary nodes
 303 :post-execution: master node, primary and secondary nodes
 304
 305 Cluster operations
 306 ~~~~~~~~~~~~~~~~~~
 307
 308 OP_CLUSTER_VERIFY
 309 +++++++++++++++++
 310
 311 Verifies the cluster status. This is a special LU with regard to
 312 hooks, as the result of the opcode will be combined with the result of
 313 post-execution hooks, in order to allow administrators to enhance the
 314 cluster verification procedure.
 315
 316 :directory: cluster-verify
 317 :env. vars: CLUSTER, MASTER, CLUSTER_TAGS, NODE_TAGS_<name>
 318 :pre-execution: none
 319 :post-execution: all nodes
 320
 321 OP_CLUSTER_RENAME
 322 +++++++++++++++++
 323
 324 Renames the cluster.
 325
 326 :directory: cluster-rename
 327 :env. vars: NEW_NAME
 328 :pre-execution: master-node
 329 :post-execution: master-node
 330
 331 OP_CLUSTER_SET_PARAMS
 332 +++++++++++++++++++++
 333
 334 Modifies the cluster parameters.
 335
 336 :directory: cluster-modify
 337 :env. vars: NEW_VG_NAME
 338 :pre-execution: master node
 339 :post-execution: master node
 340
 341
 342 Obsolete operations
 343 ~~~~~~~~~~~~~~~~~~~
 344
 345 The following operations are no longer present or don't execute hooks
 346 anymore in Ganeti 2.0:
 347
 348 - OP_INIT_CLUSTER
 349 - OP_MASTER_FAILOVER
 350 - OP_INSTANCE_ADD_MDDRBD
 351 - OP_INSTANCE_REMOVE_MDDRBD
 352
 353
 354 Environment variables
 355 ---------------------
 356
 357 Note that all variables listed here are actually prefixed with
 358 *GANETI_* in order to provide a clear namespace.
 359
 360 Common variables
 361 ~~~~~~~~~~~~~~~~
 362
 363 This is the list of environment variables supported by all operations:
 364
 365 HOOKS_VERSION
 366   Documents the hooks interface version. In case this doesnt match
 367   what the script expects, it should not run. The documents conforms
 368   to the version 2.
 369
 370 HOOKS_PHASE
 371   One of *PRE* or *POST* denoting which phase are we in.
 372
 373 CLUSTER
 374   The cluster name.
 375
 376 MASTER
 377   The master node.
 378
 379 OP_CODE
 380   One of the *OP_* values from the list of operations.
 381
 382 OBJECT_TYPE
 383   One of ``INSTANCE``, ``NODE``, ``CLUSTER``.
 384
 385 DATA_DIR
 386   The path to the Ganeti configuration directory (to read, for
 387   example, the *ssconf* files).
 388
 389
 390 Specialised variables
 391 ~~~~~~~~~~~~~~~~~~~~~
 392
 393 This is the list of variables which are specific to one or more
 394 operations.
 395
 396 INSTANCE_NAME
 397   The name of the instance which is the target of the operation.
 398
 399 INSTANCE_DISK_TEMPLATE
 400   The disk type for the instance.
 401
 402 INSTANCE_DISK_COUNT
 403   The number of disks for the instance.
 404
 405 INSTANCE_DISKn_SIZE
 406   The size of disk *n* for the instance.
 407
 408 INSTANCE_DISKn_MODE
 409   Either *rw* for a read-write disk or *ro* for a read-only one.
 410
 411 INSTANCE_NIC_COUNT
 412   The number of NICs for the instance.
 413
 414 INSTANCE_NICn_BRIDGE
 415   The bridge to which the *n* -th NIC of the instance is attached.
 416
 417 INSTANCE_NICn_IP
 418   The IP (if any) of the *n* -th NIC of the instance.
 419
 420 INSTANCE_NICn_MAC
 421   The MAC address of the *n* -th NIC of the instance.
 422
 423 INSTANCE_OS_TYPE
 424   The name of the instance OS.
 425
 426 INSTANCE_PRIMARY
 427   The name of the node which is the primary for the instance.
 428
 429 INSTANCE_SECONDARIES
 430   Space-separated list of secondary nodes for the instance.
 431
 432 INSTANCE_MEMORY
 433   The memory size (in MiBs) of the instance.
 434
 435 INSTANCE_VCPUS
 436   The number of virtual CPUs for the instance.
 437
 438 INSTANCE_STATUS
 439   The run status of the instance.
 440
 441 NODE_NAME
 442   The target node of this operation (not the node on which the hook
 443   runs).
 444
 445 NODE_PIP
 446   The primary IP of the target node (the one over which inter-node
 447   communication is done).
 448
 449 NODE_SIP
 450   The secondary IP of the target node (the one over which drbd
 451   replication is done). This can be equal to the primary ip, in case
 452   the cluster is not dual-homed.
 453
 454 FORCE
 455   This is provided by some operations when the user gave this flag.
 456
 457 IGNORE_CONSISTENCY
 458   The user has specified this flag. It is used when failing over
 459   instances in case the primary node is down.
 460
 461 ADD_MODE
 462   The mode of the instance create: either *create* for create from
 463   scratch or *import* for restoring from an exported image.
 464
 465 SRC_NODE, SRC_PATH, SRC_IMAGE
 466   In case the instance has been added by import, these variables are
 467   defined and point to the source node, source path (the directory
 468   containing the image and the config file) and the source disk image
 469   file.
 470
 471 NEW_SECONDARY
 472   The name of the node on which the new mirror component is being
 473   added. This can be the name of the current secondary, if the new
 474   mirror is on the same secondary.
 475
 476 OLD_SECONDARY
 477   The name of the old secondary in the replace-disks command Note that
 478   this can be equal to the new secondary if the secondary node hasn't
 479   actually changed.
 480
 481 EXPORT_NODE
 482   The node on which the exported image of the instance was done.
 483
 484 EXPORT_DO_SHUTDOWN
 485   This variable tells if the instance has been shutdown or not while
 486   doing the export. In the "was shutdown" case, it's likely that the
 487   filesystem is consistent, whereas in the "did not shutdown" case,
 488   the filesystem would need a check (journal replay or full fsck) in
 489   order to guarantee consistency.
 490
 491 CLUSTER_TAGS
 492   The list of cluster tags, space separated.
 493
 494 NODE_TAGS_<name>
 495   The list of tags for node *<name>*, space separated.
 496
 497 Examples
 498 --------
 499
 500 The startup of an instance will pass this environment to the hook
 501 script::
 502
 503   GANETI_CLUSTER=cluster1.example.com
 504   GANETI_DATA_DIR=/var/lib/ganeti
 505   GANETI_FORCE=False
 506   GANETI_HOOKS_PATH=instance-start
 507   GANETI_HOOKS_PHASE=post
 508   GANETI_HOOKS_VERSION=2
 509   GANETI_INSTANCE_DISK0_MODE=rw
 510   GANETI_INSTANCE_DISK0_SIZE=128
 511   GANETI_INSTANCE_DISK_COUNT=1
 512   GANETI_INSTANCE_DISK_TEMPLATE=drbd
 513   GANETI_INSTANCE_MEMORY=128
 514   GANETI_INSTANCE_NAME=instance2.example.com
 515   GANETI_INSTANCE_NIC0_BRIDGE=xen-br0
 516   GANETI_INSTANCE_NIC0_IP=
 517   GANETI_INSTANCE_NIC0_MAC=aa:00:00:a5:91:58
 518   GANETI_INSTANCE_NIC_COUNT=1
 519   GANETI_INSTANCE_OS_TYPE=debootstrap
 520   GANETI_INSTANCE_PRIMARY=node3.example.com
 521   GANETI_INSTANCE_SECONDARIES=node5.example.com
 522   GANETI_INSTANCE_STATUS=down
 523   GANETI_INSTANCE_VCPUS=1
 524   GANETI_MASTER=node1.example.com
 525   GANETI_OBJECT_TYPE=INSTANCE
 526   GANETI_OP_CODE=OP_INSTANCE_STARTUP
 527   GANETI_OP_TARGET=instance2.example.com