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