This patch adds document describes an enhancement of Ganeti's customisation by introducing global hooks that will be run before and after each Ganeti opcode execution even if the job process dies.
Signed-off-by: Oleg Ponomarev <[email protected]> --- Makefile.am | 1 + doc/design-draft.rst | 1 + doc/design-global-hooks.rst | 83 +++++++++++++++++++++++++++++++++++++++++++++ doc/hooks.rst | 7 ++++ 4 files changed, 92 insertions(+) create mode 100644 doc/design-global-hooks.rst diff --git a/Makefile.am b/Makefile.am index 50bc5d4..d0d7c71 100644 --- a/Makefile.am +++ b/Makefile.am @@ -682,6 +682,7 @@ docinput = \ doc/design-draft.rst \ doc/design-file-based-disks-ownership.rst \ doc/design-file-based-storage.rst \ + doc/design-global-hooks.rst \ doc/design-glusterfs-ganeti-support.rst \ doc/design-hotplug.rst \ doc/design-hroller.rst \ diff --git a/doc/design-draft.rst b/doc/design-draft.rst index 49e7ab9..180bee8 100644 --- a/doc/design-draft.rst +++ b/doc/design-draft.rst @@ -29,6 +29,7 @@ Design document drafts design-memory-over-commitment.rst design-macvtap.rst design-n-m-redundancy.rst + design-global-hooks.rst .. vim: set textwidth=72 : .. Local Variables: diff --git a/doc/design-global-hooks.rst b/doc/design-global-hooks.rst new file mode 100644 index 0000000..8c03e88 --- /dev/null +++ b/doc/design-global-hooks.rst @@ -0,0 +1,83 @@ +============================================== +Better Ganeti customization using global hooks +============================================== + +This document describes an enhancement of Ganeti's customisation by +introducing global hooks that will be run before and after each Ganeti +opcode even if the job process dies. + +.. contents:: :depth: 4 + +Current state and shortcomings +============================== + +Currently, Ganeti allows customization of operations by running 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``). Post +hooks for opcodes don't run in case of the job process die. + +:doc:`hooks` design document describes currently existing hooks in more +details. + +In some situations, e.g., reporting to upper level tools controlling +Ganeti, it is desirable to run hooks before and after each opcode +execution. Users currently work around this problem by creating symbolic +links for each opcode directory. But in that case a problem of the job +processes death remains. In that case post-opcode hooks wouldn't run +because the opcode execution didn't finish. + +Proposed changes +================ + +Introduce the new type of hooks, the *global* hooks, that run before +and after each opcode execution even in case of opcode process death. + +Organization of such hooks will be preserved the same as for +:ref:`existing per-opcode hooks <hooks-organization>`. The same +:ref:`common variables <common-variables>` will be available as for the +usual hooks. In addition to common variables, +:ref:`specialized variables <specialized-variables>`, corresponding to +the surrounded opcode, will also be provided. See +:ref:`per-opcode hooks parameters documentation <opcode-params>` for +more details. + +Additional variables +~~~~~~~~~~~~~~~~~~~~ + +Two additional variables are introduced for both pre and post hooks +in order to identify the current job: + +JOB_ID + Id of the job current opcode belongs to. + +OPCODE + The name of current opcode in the uppercase format + (e.g. OP_NODE_MIGRATE). See :ref:`operation list <opcode-params>` + from the original ':doc:`hooks`' design document for the exhaustive + list of operations. + +Due to the fact that global hooks will be executed even after job +process die, new environmental variable is introduced for the *global* +post hooks: + +STATUS + String containing status of the opcode execution: ``succeeded``, + ``failed`` or ``disappeared``. + + The ``succeded`` status means that the logical unit corresponding to + opcode succesfully finished. + + The ``failed`` status means that the corresponding logical unit caused + an exception which has been logged. + + The ``disappeared`` status means that opcode process has died during + the logical unit execution. + + +.. vim: set textwidth=72 : +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: diff --git a/doc/hooks.rst b/doc/hooks.rst index de794bb..bca91cd 100644 --- a/doc/hooks.rst +++ b/doc/hooks.rst @@ -17,6 +17,8 @@ are named ``$hook-$phase.d``, where ``$phase`` is either ``pre`` or This is similar to the ``/etc/network/`` structure present in Debian for network interface handling. +.. _hooks-organization: + Organisation ------------ @@ -112,6 +114,8 @@ environments, but most of the variables are common. Operation list -------------- +.. _opcode-params: + Node operations ~~~~~~~~~~~~~~~ @@ -570,6 +574,8 @@ 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: + Common variables ~~~~~~~~~~~~~~~~ @@ -599,6 +605,7 @@ DATA_DIR The path to the Ganeti configuration directory (to read, for example, the *ssconf* files). +.. _specialized-variables: Specialised variables ~~~~~~~~~~~~~~~~~~~~~ -- 2.6.0.rc2.230.g3dd15c0
