Rename OpDiagnoseOS and LUDiagnoseOS

[ganeti-local] / doc / hooks.rst

diff --git a/doc/hooks.rst b/doc/hooks.rst
index ecd6c9e..6d21882 100644 (file)
--- a/doc/hooks.rst
+++ b/doc/hooks.rst
@@ -120,7 +120,7 @@ OP_ADD_NODE
 Adds a node to the cluster.
 
 :directory: 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
 
 :pre-execution: all existing nodes
 :post-execution: all nodes plus the new node
 

@@ -128,12 +128,14 @@ Adds a node to the cluster.
 OP_REMOVE_NODE
 ++++++++++++++
 
 OP_REMOVE_NODE
 ++++++++++++++
 

-Removes a node from the cluster.
+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
 
 :directory: node-remove
 :env. vars: NODE_NAME
 :pre-execution: all existing nodes except the removed node

-:post-execution: all existing nodes except the removed node
+:post-execution: all existing nodes

 
 OP_NODE_SET_PARAMS
 ++++++++++++++++++
 
 OP_NODE_SET_PARAMS
 ++++++++++++++++++

@@ -141,7 +143,7 @@ OP_NODE_SET_PARAMS
 Changes a node's parameters.
 
 :directory: node-modify
 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
 
 :pre-execution: master node, the target node
 :post-execution: master node, the target node
 

@@ -155,12 +157,68 @@ Relocate secondary instances from a node.
 :pre-execution: master node, target node
 :post-execution: master node, target node
 
 :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 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_OS_TYPE, INSTANCE_DISK_TEMPLATE, INSTANCE_MEMORY,
 INSTANCE_DISK_SIZES, INSTANCE_VCPUS, INSTANCE_NIC_COUNT,
 INSTANCE_NICn_IP, INSTANCE_NICn_BRIDGE, INSTANCE_NICn_MAC,

@@ -195,19 +253,18 @@ OP_BACKUP_EXPORT
 
 Exports the instance.
 
 
 Exports the instance.
 

-

 :directory: instance-export
 :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
 
 :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
 
 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
 
 :pre-execution: master node, primary and secondary nodes
 :post-execution: master node, primary and secondary nodes
 

@@ -216,8 +273,8 @@ OP_INSTANCE_SHUTDOWN
 
 Stops an instance.
 
 
 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
 
 :pre-execution: master node, primary and secondary nodes
 :post-execution: master node, primary and secondary nodes
 

@@ -227,39 +284,43 @@ OP_INSTANCE_REBOOT
 Reboots an instance.
 
 :directory: 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
 
 :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
 
 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
 ++++++++++++++++++++
 
 :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
 
 :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
 :pre-execution: master node, secondary node

-:post-execution: master node, secondary node
+:post-execution: master node, primary and secondary nodes

 
 OP_INSTANCE_MIGRATE
 ++++++++++++++++++++
 
 
 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
+:directory: instance-migrate
+:env. vars: MIGRATE_LIVE, MIGRATE_CLEANUP, OLD_PRIMARY, OLD_SECONDARY, NEW_PRIMARY, NEW_SECONDARY

 :pre-execution: master node, secondary node
 :pre-execution: master node, secondary node

-:post-execution: master node, secondary node
+:post-execution: master node, primary and secondary nodes

 
 
 OP_INSTANCE_REMOVE
 
 
 OP_INSTANCE_REMOVE

@@ -268,9 +329,9 @@ OP_INSTANCE_REMOVE
 Remove an instance.
 
 :directory: instance-remove
 Remove an instance.
 
 :directory: instance-remove

-:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES
+:env. vars: SHUTDOWN_TIMEOUT

 :pre-execution: master node
 :pre-execution: master node

-:post-execution: master node
+:post-execution: master node, primary and secondary nodes

 
 OP_INSTANCE_REPLACE_DISKS
 +++++++++++++++++++++++++
 
 OP_INSTANCE_REPLACE_DISKS
 +++++++++++++++++++++++++

@@ -289,8 +350,8 @@ Grows the disk of an instance.
 
 :directory: disk-grow
 :env. vars: DISK, AMOUNT
 
 :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
 ++++++++++++++++++
 
 OP_INSTANCE_RENAME
 ++++++++++++++++++

@@ -302,9 +363,62 @@ Renames an instance.
 :pre-execution: master node, primary and secondary nodes
 :post-execution: master node, primary and secondary nodes
 
 :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
+
+

 Cluster operations
 ~~~~~~~~~~~~~~~~~~
 
 Cluster operations
 ~~~~~~~~~~~~~~~~~~
 

+OP_POST_INIT_CLUSTER
+++++++++++++++++++++
+
+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
+++++++++++++++++++
+
+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
 +++++++++++++++++
 

@@ -396,9 +510,15 @@ operations.
 INSTANCE_NAME
   The name of the instance which is the target of the operation.
 
 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.
 
 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_DISK_COUNT
   The number of disks for the instance.
 

@@ -408,6 +528,12 @@ INSTANCE_DISKn_SIZE
 INSTANCE_DISKn_MODE
   Either *rw* for a read-write disk or *ro* for a read-only one.
 
 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_NIC_COUNT
   The number of NICs for the instance.
 

@@ -420,14 +546,23 @@ INSTANCE_NICn_IP
 INSTANCE_NICn_MAC
   The MAC address of the *n* -th NIC of 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
 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_MEMORY
   The memory size (in MiBs) of the instance.

@@ -438,6 +573,12 @@ INSTANCE_VCPUS
 INSTANCE_STATUS
   The run status 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.
+

 NODE_NAME
   The target node of this operation (not the node on which the hook
   runs).
 NODE_NAME
   The target node of this operation (not the node on which the hook
   runs).

@@ -470,13 +611,22 @@ SRC_NODE, SRC_PATH, SRC_IMAGE
 
 NEW_SECONDARY
   The name of the node on which the new mirror component is being
 
 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
 
 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
   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.
 
 EXPORT_NODE
   The node on which the exported image of the instance was done.

@@ -488,6 +638,24 @@ EXPORT_DO_SHUTDOWN
   the filesystem would need a check (journal replay or full fsck) in
   order to guarantee consistency.
 
   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.
 
 CLUSTER_TAGS
   The list of cluster tags, space separated.
 

@@ -518,10 +686,16 @@ script::
   GANETI_INSTANCE_NIC_COUNT=1
   GANETI_INSTANCE_OS_TYPE=debootstrap
   GANETI_INSTANCE_PRIMARY=node3.example.com
   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
   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: