Statistics
| Branch: | Tag: | Revision:

root / doc / hooks.rst @ 1e82bc80

History | View | Annotate | Download (13.5 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.
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