hooks.rst



Ganeti customisation using hooks
Documents ganeti version 2.0

Contents

Introduction

Organisation
pre scripts
post scripts
Naming
Order of execution
Execution environment


Operation list

Node operations
OP_ADD_NODE
OP_REMOVE_NODE
OP_NODE_SET_PARAMS
OP_NODE_EVACUATE
OP_NODE_MIGRATE


Node group operations
OP_ADD_GROUP
OP_GROUP_SET_PARAMS
OP_REMOVE_GROUP
OP_RENAME_GROUP


Instance operations
OP_INSTANCE_ADD
OP_INSTANCE_REINSTALL
OP_BACKUP_EXPORT
OP_INSTANCE_STARTUP
OP_INSTANCE_SHUTDOWN
OP_INSTANCE_REBOOT
OP_INSTANCE_SET_PARAMS
OP_INSTANCE_FAILOVER
OP_INSTANCE_MIGRATE
OP_INSTANCE_REMOVE
OP_INSTANCE_REPLACE_DISKS
OP_INSTANCE_GROW_DISK
OP_INSTANCE_RENAME
OP_INSTANCE_MOVE
OP_INSTANCE_RECREATE_DISKS
OP_INSTANCE_REPLACE_DISKS


Cluster operations
OP_POST_INIT_CLUSTER
OP_DESTROY_CLUSTER
OP_CLUSTER_VERIFY
OP_CLUSTER_RENAME
OP_CLUSTER_SET_PARAMS


Obsolete operations


Environment variables
Common variables
Specialised variables


Examples


Introduction
In order to allow customisation of operations, ganeti runs scripts
under /etc/ganeti/hooks based on certain rules.
This is similar to the /etc/network/ structure present in Debian
for network interface handling.

Organisation
For every operation, two sets of scripts are run:

pre phase (for authorization/checking)
post phase (for logging)

Also, for each operation, the scripts are run on one or more nodes,
depending on the operation type.
Note that, even though we call them scripts, we are actually talking
about any executable.

pre scripts
The pre scripts have a definite target: to check that the operation
is allowed given the site-specific constraints. You could have, for
example, a rule that says every new instance is required to exists in
a database; to implement this, you could write a script that checks
the new instance parameters against your database.
The objective of these scripts should be their return code (zero or
non-zero for success and failure). However, if they modify the
environment in any way, they should be idempotent, as failed
executions could be restarted and thus the script(s) run again with
exactly the same parameters.
Note that if a node is unreachable at the time a hooks is run, this
will not be interpreted as a deny for the execution. In other words,
only an actual error returned from a script will cause abort, and not
an unreachable node.
Therefore, if you want to guarantee that a hook script is run and
denies an action, it's best to put it on the master node.

post scripts
These scripts should do whatever you need as a reaction to the
completion of an operation. Their return code is not checked (but
logged), and they should not depend on the fact that the pre scripts
have been run.

Naming
The allowed names for the scripts consist of (similar to run-parts )
upper and lower case, digits, underscores and hyphens. In other words,
the regexp ^[a-zA-Z0-9_-]+$. Also, non-executable scripts will be
ignored.

Order of execution
On a single node, the scripts in a directory are run in lexicographic
order (more exactly, the python string comparison order). It is
advisable to implement the usual NN-name convention where NN is a
two digit number.
For an operation whose hooks are run on multiple nodes, there is no
specific ordering of nodes with regard to hooks execution; you should
assume that the scripts are run in parallel on the target nodes
(keeping on each node the above specified ordering).  If you need any
kind of inter-node synchronisation, you have to implement it yourself
in the scripts.

Execution environment
The scripts will be run as follows:

no command line arguments
no controlling tty

stdin is actually /dev/null

stdout and stderr are directed to files
PATH is reset to /sbin:/bin:/usr/sbin:/usr/bin

the environment is cleared, and only ganeti-specific variables will
be left

All information about the cluster is passed using environment
variables. Different operations will have sligthly different
environments, but most of the variables are common.

Operation list

Node operations

OP_ADD_NODE
Adds a node to the cluster.


directory:
node-add


env. vars:
NODE_NAME, NODE_PIP, NODE_SIP, MASTER_CAPABLE, VM_CAPABLE


pre-execution:
all existing nodes


post-execution:
all nodes plus the new node


OP_REMOVE_NODE
Removes a node from the cluster. On the removed node the hooks are
called during the execution of the operation and not after its
completion.


directory:
node-remove


env. vars:
NODE_NAME


pre-execution:
all existing nodes except the removed node


post-execution:
all existing nodes


OP_NODE_SET_PARAMS
Changes a node's parameters.


directory:
node-modify


env. vars:
MASTER_CANDIDATE, OFFLINE, DRAINED, MASTER_CAPABLE, VM_CAPABLE


pre-execution:
master node, the target node


post-execution:
master node, the target node


OP_NODE_EVACUATE
Relocate secondary instances from a node.


directory:
node-evacuate


env. vars:
NEW_SECONDARY, NODE_NAME


pre-execution:
master node, target node


post-execution:
master node, target node


OP_NODE_MIGRATE
Relocate secondary instances from a node.


directory:
node-migrate


env. vars:
NODE_NAME


pre-execution:
master node


post-execution:
master node


Node group operations

OP_ADD_GROUP
Adds a node group to the cluster.


directory:
group-add


env. vars:
GROUP_NAME


pre-execution:
master node


post-execution:
master node


OP_GROUP_SET_PARAMS
Changes a node group's parameters.


directory:
group-modify


env. vars:
GROUP_NAME, NEW_ALLOC_POLICY


pre-execution:
master node


post-execution:
master node


OP_REMOVE_GROUP
Removes a node group from the cluster. Since the node group must be
empty for removal to succeed, the concept of "nodes in the group" does
not exist, and the hook is only executed in the master node.


directory:
group-remove


env. vars:
GROUP_NAME


pre-execution:
master node


post-execution:
master node


OP_RENAME_GROUP
Renames a node group.


directory:
group-rename


env. vars:
OLD_NAME, NEW_NAME


pre-execution:
master node and all nodes in the group


post-execution:
master node and all nodes in the group


Instance operations
All instance operations take at least the following variables:
INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARY,
INSTANCE_OS_TYPE, INSTANCE_DISK_TEMPLATE, INSTANCE_MEMORY,
INSTANCE_DISK_SIZES, INSTANCE_VCPUS, INSTANCE_NIC_COUNT,
INSTANCE_NICn_IP, INSTANCE_NICn_BRIDGE, INSTANCE_NICn_MAC,
INSTANCE_DISK_COUNT, INSTANCE_DISKn_SIZE, INSTANCE_DISKn_MODE.
The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the
properties of the n -th NIC and disk, and are zero-indexed.

OP_INSTANCE_ADD
Creates a new instance.


directory:
instance-add


env. vars:
ADD_MODE, SRC_NODE, SRC_PATH, SRC_IMAGES


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_REINSTALL
Reinstalls an instance.


directory:
instance-reinstall


env. vars:
only the standard instance vars


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_BACKUP_EXPORT
Exports the instance.


directory:
instance-export


env. vars:
EXPORT_MODE, EXPORT_NODE, EXPORT_DO_SHUTDOWN, REMOVE_INSTANCE


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_STARTUP
Starts an instance.


directory:
instance-start


env. vars:
FORCE


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_SHUTDOWN
Stops an instance.


directory:
instance-stop


env. vars:
TIMEOUT


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_REBOOT
Reboots an instance.


directory:
instance-reboot


env. vars:
IGNORE_SECONDARIES, REBOOT_TYPE, SHUTDOWN_TIMEOUT


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_SET_PARAMS
Modifies the instance parameters.


directory:
instance-modify


env. vars:
NEW_DISK_TEMPLATE


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_FAILOVER
Failovers an instance. In the post phase INSTANCE_PRIMARY and
INSTANCE_SECONDARY refer to the nodes that were repectively primary
and secondary before failover.


directory:
instance-failover


env. vars:
IGNORE_CONSISTENCY, SHUTDOWN_TIMEOUT, OLD_PRIMARY, OLD_SECONDARY, NEW_PRIMARY, NEW_SECONDARY


pre-execution:
master node, secondary node


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_MIGRATE
Migrates an instance. In the post phase INSTANCE_PRIMARY and
INSTANCE_SECONDARY refer to the nodes that were repectively primary
and secondary before migration.


directory:
instance-migrate


env. vars:
MIGRATE_LIVE, MIGRATE_CLEANUP, OLD_PRIMARY, OLD_SECONDARY, NEW_PRIMARY, NEW_SECONDARY


pre-execution:
master node, secondary node


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_REMOVE
Remove an instance.


directory:
instance-remove


env. vars:
SHUTDOWN_TIMEOUT


pre-execution:
master node


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_REPLACE_DISKS
Replace an instance's disks.


directory:
mirror-replace


env. vars:
MODE, NEW_SECONDARY, OLD_SECONDARY


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_GROW_DISK
Grows the disk of an instance.


directory:
disk-grow


env. vars:
DISK, AMOUNT


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_RENAME
Renames an instance.


directory:
instance-rename


env. vars:
INSTANCE_NEW_NAME


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes


OP_INSTANCE_MOVE
Move an instance by data-copying.


directory:
instance-move


env. vars:
TARGET_NODE, SHUTDOWN_TIMEOUT


pre-execution:
master node, primary and target nodes


post-execution:
master node, primary and target nodes


OP_INSTANCE_RECREATE_DISKS
Recreate an instance's missing disks.


directory:
instance-recreate-disks


env. vars:
only the standard instance vars


pre-execution:
master node, primary and secondary nodes


post-execution:
master node, primary and secondary nodes