|
|
| (150 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| − | == Mistral DSL version 2 specification == | + | == This Wiki is no longer maintained == |
| | | | |
| − | === Introduction ===
| + | Please see the [https://docs.openstack.org/mistral/latest/user/wf_lang_v2.html Mistral Workflow language documentation]. |
| − | | |
| − | Current document fully describes Domain Specific Language (DSL) version 2 of Mistral Workflow Service. Since version 1 issued in May 2014 Mistral team completely reworked the language pursuing with the goal in mind to make it easier to understand while more consistent and flexible.
| |
| − | | |
| − | Unlike Mistral DSL v1 this second version of DSL assumes that all entities that Mistral works with like workflows, actions and triggers are completely independent in terms of how they're referenced and accessed through API (and also Python Client API and CLI). Workbooks, the entity that can combine combine workflows/actions/triggers still exist in the language but only for namespacing and convenience purposes. See [[#Workbooks|Workbooks section]] for more details.
| |
| − | | |
| − | All DSL consists of the following main object(entity) types that will be described in details next:
| |
| − | * [[#Workflows|Workflows]]
| |
| − | * [[#Actions|Actions]]
| |
| − | * [[#Triggers|Triggers]]
| |
| − | | |
| − | === Prerequisites ===
| |
| − | | |
| − | Mistral DSL is fully based on YAML and knowledge of YAML is a plus for better understanding of the material in this specification. It also takes advantage of YAQL query language to define expressions in workflow, action and trigger definitions.
| |
| − | | |
| − | * Yet Another Markup Language (YAML): http://yaml.org
| |
| − | * Yet Another Query Language (YAQL): https://pypi.python.org/pypi/yaql/0.3
| |
| − | | |
| − | === Workflows ===
| |
| − | | |
| − | Workflow is the main building block of Mistral DSL, the reason why the project exists. Workflow represents a process that can be described in a various number of ways and that can do some job interesting to the end user. Each workflow consists of tasks (at least one) describing what exact steps should be made during workflow execution.
| |
| − | | |
| − | ===== YAML example =====
| |
| − | | |
| − | create_vm:
| |
| − | type: direct
| |
| − | input:
| |
| − | - vm_name
| |
| − | - image_ref
| |
| − | - flavor_ref
| |
| − | output:
| |
| − | vm_id: $.vm_id
| |
| − |
| |
| − | tasks:
| |
| − | create_server:
| |
| − | action: nova.servers_create name={$.vm_name} image={$.image_ref} flavor={$.flavor_ref}
| |
| − | publish:
| |
| − | vm_id: $.id
| |
| − | on-success:
| |
| − | - wait_for_instance
| |
| − |
| |
| − | wait_for_instance:
| |
| − | action: nova.servers_find id={$.vm_id} status='ACTIVE'
| |
| − | policies:
| |
| − | retry:
| |
| − | delay: 5
| |
| − | count: 15
| |
| − | | |
| − | ==== Workflow Types ====
| |
| − | Mistral DSL v2 introduces different workflow types and the structure of each workflow type varies according to its semantics. Currently, Mistral provides two workflow types:
| |
| − | | |
| − | * [[#Direct Workflow|Direct workflow]]
| |
| − | * [[#Reverse Workflow|Reverse workflow]]
| |
| − | | |
| − | See corresponding sections for details.
| |
| − | | |
| − | ==== Common Workflow Attributes ====
| |
| − | | |
| − | * '''type''' - Workflow type. Either 'direct' or 'reverse'. ''Required''.
| |
| − | * '''input''' - List of required input parameter names. ''Optional''.
| |
| − | * '''output''' - Any data structure arbitrarily containing containing YAQL expressions that defines workflow output. ''Optional''.
| |
| − | * '''task-defaults''' - Default values for some of task attributes defined at workflow level. ''Optional''. Corresponding attribute defined for a specific task always takes precedence. Specific task attributes that could be defined in '''task-defaults''' are the following:
| |
| − | ** '''on-error'''
| |
| − | ** '''on-success'''
| |
| − | ** '''on-complete'''
| |
| − | ** '''policies'''
| |
| − | * '''tasks''' - Dictionary containing workflow tasks. See below for more details. ''Required''.
| |
| − | | |
| − | ==== Tasks ====
| |
| − | | |
| − | Task is what a workflow consists of. It defines a specific computational step in the workflow. Each task can optionally take input data and produce output. In Mistral DSL v2 task can be associated with an action or with calling a workflow. In the example below there are two tasks of different types:
| |
| − | | |
| − | action_based_task:
| |
| − | action: std.http url='openstack.org'
| |
| − |
| |
| − | workflow_based_task:
| |
| − | workflow: backup_vm_workflow vm_id={$.vm_id}
| |
| − | | |
| − | Actions will be explained below in a individual paragraph but looking ahead it's worth saying that Mistral provides a lot of actions out of the box (including actions for most of the core OpenStack services) and it's also easy to plug new actions into Mistral.
| |
| − | | |
| − | ===== Common Attributes =====
| |
| − | | |
| − | All Mistral tasks regardless of workflow type have the following common attributes:
| |
| − | | |
| − | * '''action''' - Name of the action associated with the task. ''Required but mutually exclusive with'' '''workflow'''.
| |
| − | * '''workflow''' - Name of the workflow associated with the task. ''Mutually exclusive with'' '''action'''.
| |
| − | * '''input''' - Actual parameters of the task. ''Optional''. Value of each parameter is a JSON-compliant type such as number, string etc, dictionary or list. It can also be a YAQL expression to retrieve value from task context or any of the mentioned types containing inline YAQL expressions (for example, string "{$.movie_name} is a cool movie!")
| |
| − | * '''publish''' - Any JSON-compatible data structure optionally containing YAQL expression defining what needs to be published to a workflow context. Published results will be accessible for downstream tasks via using YAQL expressions. ''Optional''.
| |
| − | | |
| − | ==== Direct Workflow ====
| |
| − | | |
| − | TODO
| |
| − | | |
| − | ===== YAML example =====
| |
| − | | |
| − | create_vm:
| |
| − | type: direct
| |
| − | input:
| |
| − | - vm_name
| |
| − | - image_id
| |
| − | - flavor_id
| |
| − | output:
| |
| − | result: $.vm_id
| |
| − |
| |
| − | tasks:
| |
| − | create_vm:
| |
| − | action: nova.servers_create name={$.vm_name} image={$.image_id} flavor={$.flavor_id}
| |
| − | publish:
| |
| − | vm_id: $.id
| |
| − | on-error:
| |
| − | - send_error_email
| |
| − | on-success:
| |
| − | - send_success_email
| |
| − |
| |
| − | send_error_email:
| |
| − | action: send_email to='admin@mysite.org' body='Failed to create a VM'
| |
| − | on_complete:
| |
| − | - fail
| |
| − |
| |
| − | send_success_email:
| |
| − | action: send_email to='admin@mysite.org' body='Vm is successfully created and its id: {$.vm_id}'
| |
| − | | |
| − | ===== Attributes =====
| |
| − | | |
| − | * '''tasks''' - list of tasks in this workflow, each task represents a computational step in the workflow.
| |
| − | | |
| − | ===== Direct Workflow Task Attributes =====
| |
| − | | |
| − | TODO
| |
| − | | |
| − | * '''on-success''' - task which will be scheduled on execution after current task has finished with state 'SUCCESS'
| |
| − | * '''on-error''' - task which will be scheduled on execution after current task has finished with state 'ERROR'
| |
| − | * '''on-finish''' - task which will be scheduled on execution after current task has finished
| |
| − | | |
| − | ==== Reverse Workflow ====
| |
| − | | |
| − | TODO
| |
| − | | |
| − | ===== YAML example =====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ===== Attributes =====
| |
| − | | |
| − | * '''tasks''' - list of tasks in this workflow, each task represents a computational step in the workflow.
| |
| − | | |
| − | ===== Reverse Workflow Task Attributes =====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | * '''requires''' - list of tasks which should be execute before this tasks, or list of task names as a keys and condition as a value, this is optional parameter
| |
| − | | |
| − | === Actions ===
| |
| − | | |
| − | '''TODO''': Mention system and ad-hoc actions
| |
| − | | |
| − | ==== System Actions ====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ==== Ad-hoc actions ====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ===== YAML example =====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ===== Attributes =====
| |
| − | | |
| − | * '''name''' - action name (string without space, mandatory attribute).
| |
| − | * '''base''' - name of base action that this action is built on top of.
| |
| − | * '''base-input''' - dictionary whose structure is defined by action class. For example, for 'std.http' action it contains 'url', 'method', 'body' and 'headers' according to HTTP protocol specification.
| |
| − | * '''input''' - list containing parameter names which should or could be specified in task. This attribute is optional and used only for documenting purposes.
| |
| − | * '''output''' - any data structure defining how to transform the output of base action into the output of this action. I can optionally have YAQL expressions to access properties of base action output.
| |
| − | | |
| − | === Triggers [coming in version 0.2.0] ===
| |
| − | | |
| − | '''NOTE''': Triggers are not yet implemented as part of version 0.1.0, they will go into 0.2.0
| |
| − | | |
| − | Using triggers it is possible to run workflows according to specific rules: periodically setting a cron (http://en.wikipedia.org/wiki/Cron) pattern or on external events like ceilometer alarm.
| |
| − | | |
| − | ==== YAML example ====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ==== Attributes ====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | === Workbooks ===
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ==== YAML example ====
| |
| − | | |
| − | '''TODO'''
| |
| − | | |
| − | ==== Attributes ====
| |
| − | | |
| − | '''TODO'''
| |
