This commit adds the design document for introducing "reason trails", tracing the reason why opcodes are executed, step by step.
Signed-off-by: Michele Tartara <[email protected]> --- Makefile.am | 1 + doc/design-draft.rst | 3 +- doc/design-reason-trail.rst | 86 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 doc/design-reason-trail.rst diff --git a/Makefile.am b/Makefile.am index 4020227..644e9f6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -398,6 +398,7 @@ docinput = \ doc/design-partitioned.rst \ doc/design-query-splitting.rst \ doc/design-query2.rst \ + doc/design-reason-trail.rst \ doc/design-resource-model.rst \ doc/design-restricted-commands.rst \ doc/design-shared-storage.rst \ diff --git a/doc/design-draft.rst b/doc/design-draft.rst index 9dd2dfc..ec5303b 100644 --- a/doc/design-draft.rst +++ b/doc/design-draft.rst @@ -2,7 +2,7 @@ Design document drafts ====================== -.. Last updated for Ganeti 2.7 +.. Last updated for Ganeti 2.8 .. toctree:: :maxdepth: 2 @@ -17,6 +17,7 @@ Design document drafts design-monitoring-agent.rst design-hroller.rst design-storagespace.rst + design-reason-trail.rst .. vim: set textwidth=72 : .. Local Variables: diff --git a/doc/design-reason-trail.rst b/doc/design-reason-trail.rst new file mode 100644 index 0000000..8e86e88 --- /dev/null +++ b/doc/design-reason-trail.rst @@ -0,0 +1,86 @@ +=================== +Ganeti reason trail +=================== + +.. contents:: :depth: 2 + +This is a design document detailing the implementation of a way for Ganeti to +track the origin and the reason of every executed command, from its starting +point (command line, remote API, some htool, etc.) to its actual execution +time. + +Current state and shortcomings +============================== + +There is currently no way to track why a job and all the operations part of it +were executed, and who or what triggered the execution. +This is an inconvenience in general, and also it makes impossible to have +certain information, such as finding the reason why an instance last changed its +status (i.e.: why it was started/stopped/rebooted/etc.), or distinguishing +an admin request from a scheduled maintenance or an automated tool's work. + +Proposed changes +================ + +We propose to introduce a new piece of information, that will be called "reason +trail", to track the path from the issuing of a command to its execution. + +The reason trail will be a list of pairs ``(source, reason)``, with: + +``source`` + The entity deciding to perform (or forward) a command. + It is represented by an arbitrary string, but strings prepended by "gnt:" + are reserved for Ganeti components, and they will be refused by the + interfaces towards the external world. + +``reason`` + The reason why the entity decided to perform the operation. + It is represented by an arbitrary string. + +The reason trail will be attached at the OpCode level and will be kept as a list +according to the internal representation of lists in the programming langauge +implementing that part of the system. When such a list has to be serialized +externally (such as on the RAPI interface), it will be serialized in JSON +format. + +Any component the operation goes through is allowed (but not required) to append +it's own reason to the list. +Other than this, the list shouldn't be modified. + +As an example here is the reason trail for a shutdown operation invoked from +the command line through the gnt-instance tool:: + + [("user", "Cleanup of unused instances"), ("gnt:gnt-instance", "stop"), + ("gnt:cmdlib", "LUInstanceShutdown"), + ("gnt:noded", "perspective_instance_reboot"), + ("gnt:backend", "InstanceShutdown"), ("gnt:hv_xen", "StopInstance")] + +where the first pair is optional and it is determined by a user-specified +message, passed to gnt-instance through a command line parameter. + +The same operation, launched by an external GUI tool, and executed through the +remote API, would have a reason trail like:: + + [("user", "Cleanup of unused instances"), ("RemoteToolName", "GUI_stop"), + ("gnt:rapi_client", "ShutdownInstance"), + ("gnt:rlib2", "instances_name_shutdown"), + ("gnt:cmdlib", "LUInstanceShutdown"), + ("gnt:noded", "perspective_instance_reboot"), + ("gnt:backend", "InstanceShutdown"), ("gnt:hv_xen", "StopInstance")] + +Implementation +============== + +The implementation will start from the operations that affect the instance +status. They will be changed so that the "reason" is passed to them. +They will then export the new expected instance status, together +with the associated reason for the monitoring daemon. + +This implementation will have to be done in such a way to be extendable to +other opcodes if/when needed. + +.. vim: set textwidth=72 : +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: -- 1.7.10.4
