openstack/deb-mistral
Code Issues Proposed changes

Small changes to docs to comply with openstack document style

Browse Source 
Change-Id: I65608499eb5793f7bdbaaf529def7bb934fc4d05
This commit is contained in:
Sharat Sharma 2016-11-17 19:41:23 +05:30
parent ae141ff013
commit 26f5658c44
5 changed files with 77 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/source/terminology/actions.rst
View File

@ -1,38 +1,45 @@
Actions
=======
A particular instruction associated with a task that needs to be performed once the task runs. It can be anything like
running a shell script, HTTP request or sending a signal to some system external to Mistral. Actions can be synchronous
or asynchronous.
A particular instruction associated with a task that needs to be performed
once the task runs. It can be anything like: running a shell script, HTTP
request or sending a signal to some system external to Mistral. Actions can be
synchronous or asynchronous.
In case of synchronous action, Mistral will send a signal to Mistral Executor and will be waiting for the result from
Executor. Once Executor completes action, it sends the result to Mistral Engine.
In case of synchronous action, Mistral will send a signal to the Mistral
Executor and will be waiting for the result from the Executor. Once the
Executor completes the action, it sends the result to the Mistral Engine.
In case of asynchronous action Mistral will send a signal to third party service and will be waiting for a corresponding
action result to be delivered back to Mistral API. Once the signal is sent, Mistral won't care more about action state
and result. Third party service should do a request to Mistral API and provide info about corresponding
*action execution* and its state and result.
In case of asynchronous action, Mistral will send a signal to third party
service and will be waiting for a corresponding action result to be delivered
back to the Mistral API. Once the signal is sent, Mistral won't care more
about action state and result. Third party service should send a request to
the Mistral API and provide info about corresponding *action execution* and
its state and result.
.. image:: /img/Mistral_actions.png
:doc:`How to work with asynchronous actions </developer/asynchronous_actions>`
System Actions
System actions
--------------
System actions are provided by Mistral out of the box and can be used by anyone. It is also possible to add system
actions for specific Mistral installation via a special plugin mechanism.
System actions are provided by Mistral out of the box and can be used by
anyone. It is also possible to add system actions for specific Mistral
installation via a special plugin mechanism.
:doc:`How to write an Action Plugin </developer/creating_custom_action>`
Ad-hoc Actions
Ad-hoc actions
--------------
Ad-hoc actions are a special types of actions that can be created by user. Ad-hoc actions are always created as a
wrapper around any other existing system actions and their main goal is to simplify using same actions many times with
similar pattern.
Ad-hoc actions are a special types of actions that can be created by user.
Ad-hoc actions are always created as a wrapper around any other existing
system actions and their main goal is to simplify using same actions
many times with similar pattern.
.. note:: Nested ad-hoc actions currently are not supported (i.e. ad-hoc action around another ad-hoc action).
.. note:: Nested ad-hoc actions currently are not supported (i.e. ad-hoc
action around another ad-hoc action).
.. note:: More about actions - :ref:`actions-dsl`.

4
doc/source/terminology/cron_triggers.rst
View File

@ -1,7 +1,9 @@
Cron-triggers
=============
Cron trigger is an object allowing to run workflow on a schedule. User specifies what workflow with what input needs to be run and also specifies how often it should be run.
Cron trigger is an object allowing to run workflow on a schedule. User
specifies what workflow with what input needs to be run and also specifies
how often it should be run.
.. image:: /img/Mistral_cron_trigger.png
:align: center

40
doc/source/terminology/executions.rst
View File

@ -1,45 +1,61 @@
Executions
==========
Executions are runtime objects and they reflect the information about the progress and state of concrete execution type. All executions are persisted in DB.
Executions are runtime objects and they reflect the information about the
progress and state of concrete execution type.
Workflow Execution
Workflow execution
------------------
A particular execution of specific workflow. When user submits a workflow to run, Mistral creates an object in database for execution of this workflow. It contains all information about workflow itself, about execution progress, state, input and output data. Workflow execution contains at least one *task execution*.
A particular execution of specific workflow. When user submits a workflow to
run, Mistral creates an object in database for execution of this workflow. It
contains all information about workflow itself, about execution progress,
state, input and output data. Workflow execution contains at least one
*task execution*.
A workflow execution can be in one of a number of predefined states reflecting its current status:
A workflow execution can be in one of a number of predefined states reflecting
its current status:
* **RUNNING** - workflow is currently being executed.
* **PAUSED** - workflow is paused.
* **SUCCESS** - workflow has finished successfully.
* **ERROR** - workflow has finished with an error.
Task Execution
Task execution
--------------
Defines a workflow execution step. It has a state and result.
**Task state**
A task can be in one of a number of predefined states reflecting its current status:
A task can be in one of a number of predefined states reflecting its current
status:
* **IDLE** - task is not started yet; probably not all requirements are satisfied.
* **WAITING** - task execution object has been created but it is not ready to start because some preconditions are not met. **NOTE:** The task may never run just because some of the preconditions may never be met.
* **RUNNING_DELAYED** - task was in the running state before and the task execution has been delayed on precise amount of time.
* **IDLE** - task is not started yet; probably not all requirements are
satisfied.
* **WAITING** - task execution object has been created but it is not ready to
start because some preconditions are not met. **NOTE:** The task may never
run just because some of the preconditions may never be met.
* **RUNNING_DELAYED** - task was in the running state before and the task
execution has been delayed on precise amount of time.
* **RUNNING** - task is currently being executed.
* **SUCCESS** - task has finished successfully.
* **ERROR** - task has finished with an error.
All the actual task states belonging to current execution are persisted in DB.
Task result is an aggregation of all *action executions* belonging to current *task execution*. Usually one *task execution* has at least one *action execution*. But in case of task is executing nested workflow, this *task execution* won't have *action executions*. Instead, there will be at least one *workflow execution*.
Task result is an aggregation of all *action executions* belonging to current
*task execution*. Usually one *task execution* has at least one
*action execution*. But in case of task is executing nested workflow, this
*task execution* won't have *action executions*. Instead, there will be at
least one *workflow execution*.
Action Execution
Action execution
----------------
Execution of specific action. To see details about actions, please refer to :ref:`actions-dsl`
Action execution has a state, input and output data.
Usually action execution belongs to task execution but Mistral also is able to run separate action executions.
Usually action execution belongs to task execution but Mistral also is able to run
separate action executions.

22
doc/source/terminology/workbooks.rst
View File

@ -1,16 +1,28 @@
Workbooks
=========
Using workbooks users can combine multiple entities of any type (workflows and actions) into one document and upload to Mistral service. When uploading a workbook Mistral will parse it and save its workflows and actions as independent objects which will be accessible via their own API endpoints (/workflows and /actions). Once it's done the workbook comes out of the game. User can just start workflows and use references to workflows/actions as if they were uploaded without workbook in the first place. However, if need to modify these individual objects user can modify the same workbook definition and re-upload it to Mistral (or, of course, user can do it independently).
Using workbooks users can combine multiple entities of any type (workflows and
actions) into one document and upload to Mistral service. When uploading a
workbook, Mistral will parse it and save its workflows and actions as
independent objects which will be accessible via their own API endpoints
(/workflows and /actions). Once it's done the workbook comes out of the game.
User can just start workflows and use references to workflows/actions as if
they were uploaded without workbook in the first place. However, if need to
modify these individual objects user can modify the same workbook definition
and re-upload it to Mistral (or, of course, user can do it independently).
**Namespacing**
One thing that's worth noting is that when using a workbook Mistral uses its name as a prefix for generating final names of workflows and actions included into the workbook. To illustrate this principle let's take a look at the figure below.
One thing that's worth noting is that when using a workbook Mistral uses its
name as a prefix for generating final names of workflows and actions included
into the workbook. To illustrate this principle let's take a look at the
figure below:
.. image:: /img/Mistral_workbook_namespacing.png
:align: center
So after a workbook has been uploaded its workflows and actions become independent objects but with slightly different names.
So after a workbook has been uploaded its workflows and actions become
independent objects but with slightly different names.
YAML example
^^^^^^^^^^^^
@ -55,7 +67,9 @@ YAML example
- str2
base: std.echo output="<% $.str1 %><% $.str2 %>"
**NOTE:** Even though names of objects inside workbooks change upon uploading Mistral allows referencing between those objects using local names declared in the original workbook.
**NOTE:** Even though names of objects inside workbooks change upon uploading
Mistral allows referencing between those objects using local names declared in
the original workbook.
**Attributes**

8
doc/source/terminology/workflows.rst
View File

@ -35,7 +35,7 @@ YAML example
        delay: 5
        count: 15
Workflow Types
Workflow types
--------------
Mistral DSL v2 introduces different workflow types and the structure of
@ -47,7 +47,7 @@ provides two workflow types:
See corresponding sections for details.
Direct Workflow
Direct workflow
---------------
Direct workflow consists of tasks combined in a graph where every next
@ -88,7 +88,7 @@ YAML example
    send_success_email:
      action: send_email to='admin@mysite.org' body='Vm is successfully created and its id: <% $.vm_id %>'
Reverse Workflow
Reverse workflow
----------------
In reverse workflow all relationships in workflow task graph are
@ -136,4 +136,4 @@ YAML example
      action: send_email to='admin@mysite.org' body='Vm is created and id <% $.vm_id %> and ip address <% $.vm_ip %>'
      requires: [create_vm, associate_ip]
For more details about DSL itself, please see :doc:`Mistral DSL specification </dsl/index>`
For more details about DSL itself, please see :doc:`Mistral DSL specification </dsl/index>`