X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/6c6b7f8a4d5f8e2b313b6f480ab44931ea87fdb1..bcd87e22bb462c87c50fc07a2cca14a977e79253:/doc/hooks.rst diff --git a/doc/hooks.rst b/doc/hooks.rst index 7407499..d276059 100644 --- a/doc/hooks.rst +++ b/doc/hooks.rst @@ -64,7 +64,7 @@ have been run. 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. @@ -114,22 +114,23 @@ Operation list 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 @@ -142,7 +143,7 @@ OP_NODE_SET_PARAMS 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 @@ -167,11 +168,57 @@ Relocate secondary instances from a 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 + + 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, @@ -181,8 +228,8 @@ The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the properties of the *n* -th NIC and disk, and are zero-indexed. -OP_INSTANCE_ADD -+++++++++++++++ +OP_INSTANCE_CREATE +++++++++++++++++++ Creates a new instance. @@ -206,19 +253,18 @@ OP_BACKUP_EXPORT 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 @@ -228,7 +274,7 @@ OP_INSTANCE_SHUTDOWN Stops an instance. :directory: instance-stop -:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES +:env. vars: TIMEOUT :pre-execution: master node, primary and secondary nodes :post-execution: master node, primary and secondary nodes @@ -238,39 +284,43 @@ OP_INSTANCE_REBOOT 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 :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-migrate -:env. vars: INSTANCE_MIGRATE_LIVE, INSTANCE_MIGRATE_CLEANUP +:env. vars: MIGRATE_LIVE, MIGRATE_CLEANUP, 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_REMOVE @@ -279,9 +329,9 @@ 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 +:post-execution: master node, primary and secondary nodes OP_INSTANCE_REPLACE_DISKS +++++++++++++++++++++++++ @@ -300,8 +350,8 @@ Grows the disk of an instance. :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 ++++++++++++++++++ @@ -319,7 +369,7 @@ OP_INSTANCE_MOVE Move an instance by data-copying. :directory: instance-move -:env. vars: TARGET_NODE +:env. vars: TARGET_NODE, SHUTDOWN_TIMEOUT :pre-execution: master node, primary and target nodes :post-execution: master node, primary and target nodes @@ -347,31 +397,32 @@ Replace the disks of an instance. 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. @@ -379,7 +430,7 @@ cluster verification procedure. :directory: cluster-verify :env. vars: CLUSTER, MASTER, CLUSTER_TAGS, NODE_TAGS_ :pre-execution: none -:post-execution: all nodes +:post-execution: all nodes in a group OP_CLUSTER_RENAME +++++++++++++++++ @@ -417,8 +468,10 @@ anymore in Ganeti 2.0: 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 ~~~~~~~~~~~~~~~~ @@ -459,9 +512,15 @@ operations. 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. @@ -471,6 +530,12 @@ INSTANCE_DISKn_SIZE 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. @@ -483,14 +548,23 @@ INSTANCE_NICn_IP 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. @@ -501,6 +575,15 @@ INSTANCE_VCPUS 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. + +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). @@ -533,13 +616,22 @@ SRC_NODE, SRC_PATH, SRC_IMAGE 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. @@ -551,6 +643,24 @@ EXPORT_DO_SHUTDOWN 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. @@ -581,10 +691,16 @@ script:: 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: