Ganeti customisation using hooks
================================
-Documents ganeti version 2.0
+Documents Ganeti version 2.7
.. contents::
Introduction
------------
-
-In order to allow customisation of operations, ganeti runs scripts
-under ``/etc/ganeti/hooks`` based on certain rules.
-
+In order to allow customisation of operations, Ganeti runs scripts in
+sub-directories of ``@SYSCONFDIR@/ganeti/hooks``. These sub-directories
+are named ``$hook-$phase.d``, where ``$phase`` is either ``pre`` or
+``post`` and ``$hook`` matches the directory name given for a hook (e.g.
+``cluster-verify-post.d`` or ``node-add-pre.d``).
This is similar to the ``/etc/network/`` structure present in Debian
for network interface handling.
Naming
~~~~~~
-The allowed names for the scripts consist of (similar to *run-parts* )
+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.
- stdout and stderr are directed to files
-- PATH is reset to ``/sbin:/bin:/usr/sbin:/usr/bin``
+- PATH is reset to :pyeval:`constants.HOOKS_PATH`
- the environment is cleared, and only ganeti-specific variables will
be left
Node operations
~~~~~~~~~~~~~~~
-OP_ADD_NODE
+OP_NODE_ADD
+++++++++++
Adds a node to the cluster.
:directory: node-add
-:env. vars: NODE_NAME, NODE_PIP, NODE_SIP
+: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
+OP_NODE_REMOVE
++++++++++++++
-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.
+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
Changes a node's parameters.
:directory: node-modify
-:env. vars: MASTER_CANDIDATE, OFFLINE, DRAINED
+: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
+OP_NODE_MIGRATE
++++++++++++++++
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
+:directory: node-migrate
+:env. vars: NODE_NAME
+:pre-execution: master node
+:post-execution: master node
+
+
+Node group operations
+~~~~~~~~~~~~~~~~~~~~~
+
+OP_GROUP_ADD
+++++++++++++
+
+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_GROUP_REMOVE
++++++++++++++++
+
+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_GROUP_RENAME
++++++++++++++++
+
+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
+
+OP_GROUP_EVACUATE
++++++++++++++++++
+
+Evacuates a node group.
+
+:directory: group-evacuate
+:env. vars: GROUP_NAME, TARGET_GROUPS
+:pre-execution: master node and all nodes in the group
+:post-execution: master node and all nodes in the group
+
+Network operations
+~~~~~~~~~~~~~~~~~~
+
+OP_NETWORK_ADD
+++++++++++++++
+
+Adds a network to the cluster.
+
+:directory: network-add
+:env. vars: NETWORK_NAME, NETWORK_SUBNET, NETWORK_GATEWAY, NETWORK_SUBNET6,
+ NETWORK_GATEWAY6, NETWORK_MAC_PREFIX, NETWORK_TAGS
+:pre-execution: master node
+:post-execution: master node
+
+OP_NETWORK_REMOVE
++++++++++++++++++
+
+Removes a network from the cluster.
+
+:directory: network-remove
+:env. vars: NETWORK_NAME
+:pre-execution: master node
+:post-execution: master node
+
+OP_NETWORK_CONNECT
+++++++++++++++++++
+
+Connects a network to a nodegroup.
+
+:directory: network-connect
+:env. vars: GROUP_NAME, NETWORK_NAME,
+ GROUP_NETWORK_MODE, GROUP_NETWORK_LINK,
+ NETWORK_SUBNET, NETWORK_GATEWAY, NETWORK_SUBNET6,
+ NETWORK_GATEWAY6, NETWORK_MAC_PREFIX, NETWORK_TAGS
+:pre-execution: nodegroup nodes
+:post-execution: nodegroup nodes
+
+
+OP_NETWORK_DISCONNECT
++++++++++++++++++++++
+
+Disconnects a network from a nodegroup.
+
+:directory: network-disconnect
+:env. vars: GROUP_NAME, NETWORK_NAME,
+ GROUP_NETWORK_MODE, GROUP_NETWORK_LINK,
+ NETWORK_SUBNET, NETWORK_GATEWAY, NETWORK_SUBNET6,
+ NETWORK_GATEWAY6, NETWORK_MAC_PREFIX, NETWORK_TAGS
+:pre-execution: nodegroup nodes
+:post-execution: nodegroup nodes
+
+
+OP_NETWORK_SET_PARAMS
++++++++++++++++++++++
+
+Modifies a network.
+
+:directory: network-modify
+:env. vars: NETWORK_NAME, NETWORK_SUBNET, NETWORK_GATEWAY, NETWORK_SUBNET6,
+ NETWORK_GATEWAY6, NETWORK_MAC_PREFIX, NETWORK_TAGS
+:pre-execution: master node
+:post-execution: master node
Instance operations
~~~~~~~~~~~~~~~~~~~
All instance operations take at least the following variables:
-INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES,
+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_NICn_NETWORK,
+INSTANCE_NICn_NETWORK_UUID, INSTANCE_NICn_NETWORK_SUBNET,
+INSTANCE_NICn_NETWORK_GATEWAY, INSTANCE_NICn_NETWORK_SUBNET6,
+INSTANCE_NICn_NETWORK_GATEWAY6, INSTANCE_NICn_NETWORK_MAC_PREFIX,
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.
+The INSTANCE_NICn_NETWORK_* variables are only passed if a NIC's network
+parameter is set (that is if the NIC is associated to a network defined
+via ``gnt-network``)
-OP_INSTANCE_ADD
-+++++++++++++++
+
+OP_INSTANCE_CREATE
+++++++++++++++++++
Creates a new instance.
Exports the instance.
-
:directory: instance-export
-:env. vars: EXPORT_NODE, EXPORT_DO_SHUTDOWN
+: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_START
-+++++++++++++++++
+OP_INSTANCE_STARTUP
++++++++++++++++++++
Starts an instance.
:directory: instance-start
-:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, FORCE
+:env. vars: FORCE
:pre-execution: master node, primary and secondary nodes
:post-execution: master node, primary and secondary nodes
Stops an instance.
-:directory: instance-shutdown
-:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES
+:directory: instance-stop
+:env. vars: TIMEOUT
:pre-execution: master node, primary and secondary nodes
:post-execution: master node, primary and secondary nodes
Reboots an instance.
:directory: instance-reboot
-:env. vars: IGNORE_SECONDARIES, REBOOT_TYPE
+: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_MODIFY
-++++++++++++++++++
+OP_INSTANCE_SET_PARAMS
+++++++++++++++++++++++
Modifies the instance parameters.
:directory: instance-modify
-:env. vars: INSTANCE_NAME, MEM_SIZE, VCPUS, INSTANCE_IP
+:env. vars: NEW_DISK_TEMPLATE, RUNTIME_MEMORY
:pre-execution: master node, primary and secondary nodes
:post-execution: master node, primary and secondary nodes
OP_INSTANCE_FAILOVER
++++++++++++++++++++
-Failovers an instance.
+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
+:env. vars: IGNORE_CONSISTENCY, SHUTDOWN_TIMEOUT, OLD_PRIMARY, OLD_SECONDARY, NEW_PRIMARY, NEW_SECONDARY
:pre-execution: master node, secondary node
-:post-execution: master node, secondary node
+:post-execution: master node, primary and secondary nodes
OP_INSTANCE_MIGRATE
++++++++++++++++++++
-Migrates an instance.
+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-failover
-:env. vars: INSTANCE_MIGRATE_LIVE, INSTANCE_MIGRATE_CLEANUP
-:pre-execution: master node, secondary node
-:post-execution: master node, secondary node
+:directory: instance-migrate
+:env. vars: MIGRATE_LIVE, MIGRATE_CLEANUP, OLD_PRIMARY, OLD_SECONDARY, NEW_PRIMARY, NEW_SECONDARY
+:pre-execution: master node, primary and secondary nodes
+:post-execution: master node, primary and secondary nodes
OP_INSTANCE_REMOVE
Remove an instance.
:directory: instance-remove
-:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES
+:env. vars: SHUTDOWN_TIMEOUT
:pre-execution: master node
-:post-execution: master node
-
-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
:directory: disk-grow
:env. vars: DISK, AMOUNT
-:pre-execution: master node, primary node
-:post-execution: master node, primary node
+:pre-execution: master node, primary and secondary nodes
+:post-execution: master node, primary and secondary nodes
OP_INSTANCE_RENAME
++++++++++++++++++
: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
+
+OP_INSTANCE_REPLACE_DISKS
++++++++++++++++++++++++++
+
+Replace the disks of an instance.
+
+:directory: mirrors-replace
+:env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY
+:pre-execution: master node, primary and new secondary nodes
+:post-execution: master node, primary and new secondary nodes
+
+OP_INSTANCE_CHANGE_GROUP
+++++++++++++++++++++++++
+
+Moves an instance to another group.
+
+:directory: instance-change-group
+:env. vars: TARGET_GROUPS
+:pre-execution: master node
+:post-execution: master node
+
+
Cluster operations
~~~~~~~~~~~~~~~~~~
-OP_POST_INIT_CLUSTER
+OP_CLUSTER_POST_INIT
++++++++++++++++++++
-This hook is called via a special "empty" LU right after cluster initialization.
+This hook is called via a special "empty" LU right after cluster
+initialization.
:directory: cluster-init
:env. vars: none
:pre-execution: none
:post-execution: master node
-OP_DESTROY_CLUSTER
+OP_CLUSTER_DESTROY
++++++++++++++++++
-The post phase of this hook is called during the execution of destroy operation
-and not after its completion.
+The post phase of this hook is called during the execution of destroy
+operation and not after its completion.
:directory: cluster-destroy
:env. vars: none
:pre-execution: none
:post-execution: master node
-OP_CLUSTER_VERIFY
-+++++++++++++++++
+OP_CLUSTER_VERIFY_GROUP
++++++++++++++++++++++++
-Verifies the cluster status. This is a special LU with regard to
+Verifies all nodes in a group. This is a special LU with regard to
hooks, as the result of the opcode will be combined with the result of
post-execution hooks, in order to allow administrators to enhance the
cluster verification procedure.
:directory: cluster-verify
:env. vars: CLUSTER, MASTER, CLUSTER_TAGS, NODE_TAGS_<name>
:pre-execution: none
-:post-execution: all nodes
+:post-execution: all nodes in a group
OP_CLUSTER_RENAME
+++++++++++++++++
:pre-execution: master node
:post-execution: master node
+Virtual operation :pyeval:`constants.FAKE_OP_MASTER_TURNUP`
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This doesn't correspond to an actual op-code, but it is called when the
+master IP is activated.
+
+:directory: master-ip-turnup
+:env. vars: MASTER_NETDEV, MASTER_IP, MASTER_NETMASK, CLUSTER_IP_VERSION
+:pre-execution: master node
+:post-execution: master node
+
+Virtual operation :pyeval:`constants.FAKE_OP_MASTER_TURNDOWN`
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This doesn't correspond to an actual op-code, but it is called when the
+master IP is deactivated.
+
+:directory: master-ip-turndown
+:env. vars: MASTER_NETDEV, MASTER_IP, MASTER_NETMASK, CLUSTER_IP_VERSION
+:pre-execution: master node
+:post-execution: master node
+
Obsolete operations
~~~~~~~~~~~~~~~~~~~
Environment variables
---------------------
-Note that all variables listed here are actually prefixed with
-*GANETI_* in order to provide a clear namespace.
+Note that all variables listed here are actually prefixed with *GANETI_*
+in order to provide a clear namespace. In addition, post-execution
+scripts receive another set of variables, prefixed with *GANETI_POST_*,
+representing the status after the opcode executed.
Common variables
~~~~~~~~~~~~~~~~
This is the list of variables which are specific to one or more
operations.
+CLUSTER_IP_VERSION
+ IP version of the master IP (4 or 6)
+
INSTANCE_NAME
The name of the instance which is the target of the operation.
+INSTANCE_BE_x,y,z,...
+ Instance BE params. There is one variable per BE param. For instance, GANETI_INSTANCE_BE_auto_balance
+
INSTANCE_DISK_TEMPLATE
The disk type for the instance.
+NEW_DISK_TEMPLATE
+ The new disk type for the instance.
+
INSTANCE_DISK_COUNT
The number of disks for the instance.
INSTANCE_DISKn_MODE
Either *rw* for a read-write disk or *ro* for a read-only one.
+INSTANCE_HV_x,y,z,...
+ Instance hypervisor options. There is one variable per option. For instance, GANETI_INSTANCE_HV_use_bootloader
+
+INSTANCE_HYPERVISOR
+ The instance hypervisor.
+
INSTANCE_NIC_COUNT
The number of NICs for the instance.
INSTANCE_NICn_MAC
The MAC address of the *n* -th NIC of the instance.
+INSTANCE_NICn_MODE
+ The mode of the *n* -th NIC of the instance.
+
INSTANCE_OS_TYPE
The name of the instance OS.
INSTANCE_PRIMARY
- The name of the node which is the primary for the instance.
+ The name of the node which is the primary for the instance. Note that
+ for migrations/failovers, you shouldn't rely on this variable since
+ the nodes change during the exectution, but on the
+ OLD_PRIMARY/NEW_PRIMARY values.
-INSTANCE_SECONDARIES
- Space-separated list of secondary nodes for the instance.
+INSTANCE_SECONDARY
+ Space-separated list of secondary nodes for the instance. Note that
+ for migrations/failovers, you shouldn't rely on this variable since
+ the nodes change during the exectution, but on the
+ OLD_SECONDARY/NEW_SECONDARY values.
INSTANCE_MEMORY
The memory size (in MiBs) of the instance.
INSTANCE_STATUS
The run status of the instance.
+MASTER_CAPABLE
+ Whether a node is capable of being promoted to master.
+
+VM_CAPABLE
+ Whether the node can host instances.
+
+MASTER_NETDEV
+ Network device of the master IP
+
+MASTER_IP
+ The master IP
+
+MASTER_NETMASK
+ Netmask of the master IP
+
+INSTANCE_TAGS
+ A space-delimited list of the instance's tags.
+
NODE_NAME
The target node of this operation (not the node on which the hook
runs).
NEW_SECONDARY
The name of the node on which the new mirror component is being
- added. This can be the name of the current secondary, if the new
- mirror is on the same secondary.
+ added (for replace disk). This can be the name of the current
+ secondary, if the new mirror is on the same secondary. For
+ migrations/failovers, this is the old primary node.
OLD_SECONDARY
- The name of the old secondary in the replace-disks command Note that
+ The name of the old secondary in the replace-disks command. Note that
this can be equal to the new secondary if the secondary node hasn't
- actually changed.
+ actually changed. For migrations/failovers, this is the new primary
+ node.
+
+OLD_PRIMARY, NEW_PRIMARY
+ For migrations/failovers, the old and respectively new primary
+ nodes. These two mirror the NEW_SECONDARY/OLD_SECONDARY variables
+
+EXPORT_MODE
+ The instance export mode. Either "remote" or "local".
EXPORT_NODE
The node on which the exported image of the instance was done.
the filesystem would need a check (journal replay or full fsck) in
order to guarantee consistency.
+REMOVE_INSTANCE
+ Whether the instance was removed from the node.
+
+SHUTDOWN_TIMEOUT
+ Amount of time to wait for the instance to shutdown.
+
+TIMEOUT
+ Amount of time to wait before aborting the op.
+
+OLD_NAME, NEW_NAME
+ Old/new name of the node group.
+
+GROUP_NAME
+ The name of the node group.
+
+NEW_ALLOC_POLICY
+ The new allocation policy for the node group.
+
CLUSTER_TAGS
The list of cluster tags, space separated.
GANETI_INSTANCE_NIC_COUNT=1
GANETI_INSTANCE_OS_TYPE=debootstrap
GANETI_INSTANCE_PRIMARY=node3.example.com
- GANETI_INSTANCE_SECONDARIES=node5.example.com
+ GANETI_INSTANCE_SECONDARY=node5.example.com
GANETI_INSTANCE_STATUS=down
GANETI_INSTANCE_VCPUS=1
GANETI_MASTER=node1.example.com
GANETI_OBJECT_TYPE=INSTANCE
GANETI_OP_CODE=OP_INSTANCE_STARTUP
GANETI_OP_TARGET=instance2.example.com
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End:
projects / ganeti-local / blobdiff