OpenStack 工作流组件： Mistral

---

1 Mistral 简介

Mistral 是由 Mirantis 开发，贡献给 OpenStack 社区的工作流组件，它提供 Workflow As a Service 服务。

在计算机中通常处理的任务是由多个连续并有依赖关系的任务组成，而且多个任务可能分布在不同的机器上执行，如物理机，虚拟机，container 等。基于这样的考虑，Mistral 应运而生，它可以灵活的编排多个任务(task)，任务之间具有一定的依赖关系，每个任务又分为多个行为(action)，行为可以在不通的机器上执行。这些任务的集合称为 Workflow，Mistral 将 Workflow 作为一种服务实现任务的编排，管理，执行。

如上图所示，Mistral service 主要有 Engine，Scheduler，API Server，Task Executor 等组件组成。各组件的主要功能有：

• Engine：从 Workflow 队列中选出 Workflow，处理 Workflow 中 task 数据转换，条件判断等操作。
• Scheduler：Engine 和 Task Executor 交互的中间组件，存储并执行延时调用的 task。
• Task Executor：从 Task 队列中选出 Task ，执行 task 的 action，将执行结果发给 Engine。
• API Server：提供 Mistral API 给用户，同时通过 Mistral API 可以监控 Workflow 的执行流。

2 部署 Mistral

2.1 Mistral 安装

Mistral 安装及配置可看这里。

2.2 Mistral 服务

安装及配置好的 Mistral 大致有以下几个服务：

• Mistral API service
• mistral-dashboard service
• Mistral Engine service
• Mistral Executor service

3 Mistral 语法

3.1 Mistral workbook 示例

---
version: '2.0'

name: my_workbook
description: My set of workflows and ad-hoc actions

workflows:
  local_workflow1:
    type: direct

    tasks:
      task1:
        action: local_action str1='Hi' str2=' Mistral!'
        on-complete:
          - task2

      task2:
        action: global_action

 

上图是 Mistral 的 workbook，它是基于 yaml 语法写的一系列 workflow 的集合。其中， workflow 对任务 task 进行编排，它在 workflows 字段下定义。task 是执行的任务，它在 tasks 字段下定义，而 action 则是任务所做的行为，它是真正处理任务的单元。

 

在本示例中，名为 my_workbook 的 workbook 中定义了一个名为 local_workflow1 的 workflow，该 workflow 会执行两个 task：task1 和 task2。task2 依赖于 task1，当 task1 执行完成之后开始执行 task2。其中，task1 会执行名为 local_action 的行为，它所需要的输入参数是 str1 和 str2，而 task2 执行的 global_action 则不需要输入参数。

 

 

值得一提的是：Mistral 自带一种称为 Namespacing 的机制，该机制使得每个 action/task/workflow 具有唯一性。如上图所示，workbook my_workbook 包含两个 workflow 和 两个 action，将该 workbook 上传到 Mistral 时，Mistral 会将它们加上 workbook 前缀，解析为 my_workbook.workflow1, my_workbook.action1 这种形式，从而保证了不同 workflow 可以使用相同的 task/action。

3.2 Mistral Workflow

Mistral 有两种类型的 Workflow，它们定义在 type 字段，分别为 direct 和 reverse：

3.2.1 direct workflow

direct workflow 示意图如上所示。它清晰的定义了 workflow 中 task 的执行顺序，task T1 执行成功会执行 T3，执行失败则执行 T2，T2 无论执行成功或失败都将执行 T4，依次类推，最终执行 T7。

 

决定 task 执行顺序的是如下特性：

• on-success：声明当前 task 执行成功将执行的 task。
• on-error：声明当前 task 执行失败将执行的 task。
• on-complete：声明无论当前 task 执行成功/失败都将执行的 task。

 

在实际编排时，往往特性下的 task 不止一个，如下例所示：

tasks:
  create_vm:
    workflow: create_vm
    input:
      operationType: <% $.operationType %>
      operationParams: <% $.operationParams %>
    publish:
      precheck_result: <% task(create_vm).result.precheck_result %>
      finalize_tag: <% task(create_vm).result.precheck_result %>
    publish-on-error:
      error_message: <% task(create_vm).result.error_message %>
      finalize_tag: "error"
    on-success:
      - check_create_vm_done: <% $.precheck_result = 'success'%>
      - set_workflow_fail: <% $.precheck_result = 'error'%>
    on-error:
      - set_workflow_fail

  check_create_vm_done:
    action: heat.stacks_get stack_id=<% $.stack.id %>
    publish:
      stack_status: <% task(check_create_vm_done).result.stack_status %>
      error_message: "something wrong!."
    publish-on-error:
      error_message: <% task(check_create_vm_done).result %>
    on-complete:
      - check_vm_exists
      - set_workflow_success

 

在该例中，task create_vm 执行成功后会检查变量值。如果变量 precheck_result 为 success，则执行 task check_create_vm_done。如果变量为 error，则执行 task set_workflow_fail。如果 task 执行失败则直接执行 set_workflow_fail。其中，<% $. %> 为 YAQL 语法，类似的有 <% $.task() %>。Mistral 支持在 workbook 中使用 YAQL 或者 jinja 表达式语言来引用，定义和使用变量。(YAQL 语法看这里, Jinja 语法看这里)

 

当执行 task check_create_vm_done 时，无论结果如何都将执行 check_vm_exists 和 set_workflow_success，它们的执行顺序是先执行 check_vm_exists ，再执行 set_workflow_success。

 

Mistral 自带 Engine command 来控制 workflow 的状态，参考这里了解更多。

3.2.2 reverse workflow

 

 

reverse workflow 如上图所示。workflow 中定义了 Target task T1 ，执行 target task T1 需要依赖 T2 的执行，同样的 T2 依赖 T6 和 T5，层层往上执行依赖的 task。在该例中，T3 和 T4 不会被执行，因为 T1 依赖的 task 并没有依赖于它们。

 

reverse workflow 需要的特性是 requires，在 requires 里定义了执行当前 task 需要执行的 task。举例，如下所示：

---
version: '2.0'

create_vm_and_send_email:
  type: reverse

  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: <% task(create_vm).result.id %>

    search_for_ip:
      action: nova.floating_ips_findall instance_id=null
      publish:
        vm_ip: <% task(search_for_ip).result[0].ip %>

    associate_ip:
      action: nova.servers_add_floating_ip server=<% $.vm_id %> address=<% $.vm_ip %>
      requires: [search_for_ip]

    send_email:
      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]

3.3.3 common workflow 语法

前面已经介绍了几个 workflow 示例，从示例中大致可以看出 workflow 主要有如下几个特性：

• type：定义 workflow 是哪种类型，direct 或 reverse。可选项，默认为 direct。
• input：提供给 workflow 的参数，参数名前加 “-”。可选项。
• output：workflow 执行的输出结果，该结果可被上一层 workflow 使用。可选项。
• tasks：workflow 定义的 task，非可选项。

3.3 Mistral task

Mistral task 主要有如下几个特性：

• name：定义的 task 名称，非可选。
• description：task 的描述文本，可选。
• action：执行 task 需要执行的 action。
• workflow：执行 task 需要执行的 workflow。task 既支持执行 action 也支持执行 workflow。
• input：task 执行需要的输入参数。
• publish：task 执行成功的输出，输出是 json 格式文本。在后面的操作中可以使用 publish 的结果。
• publish-on-error：task 执行失败的输出。
• timeout： 以秒为单位定义 task 的超时时间，如果 task 在规定时间内未完成则 task 被视为执行失败，属于 timeout policy。
• retry： 定义 task 执行失败需要执行的模式，有 count，delay，break-in 和 continue-on 特性：

get_vm_result:
    action: vm_result
    input:
      operation_parameters: <% $.operationParams %>
    retry:
      count: <% 10 %>
      delay: 30

本例中，task get_vm_result 的 action 如果执行失败后，会进入 retry 模式，重新执行 10 次 action，且每次 action 的间隔是 30 秒，直到执行成功才退出 retry 模式。它属于 retry_policy，更多 task policy 可看这里。

3.4 Mistral action

Mistral action 是真正执行任务的单元，它分为 system action 和 ad-hoc action。system action 是 Mistral 自带的 action，安装好 Mistral 即可使用。ad-hoc action 是用户在自带 action 的基础上自定义的 action。

3.4.1 system action

系统自带的 action 有很多，列几个常见 action 如下：

• std.fail：始终执行 fail，常用于 workflow 失败时执行。
• std.noop：什么都不做的 action。
• stdjavascript：执行 javascript 代码，它包含两个特性：context 和 script。context 中定义了在 script 中使用的变量，script 是javascript 语法，如下所示：

check_vm:
    action: std.javascript
    input:
      context:
        vm: <%  $.vm %>
      script: |
        if( $.vm.count != "0")
          return "yes";
        else
          return "no";

(看这里了解更多 system action)

3.4.2 ad-hoc action

ad-hoc action 是用户基于 system action 之上自定义的 action，定义好 action 之后将此 action 传给 Mistral，即可在 workflow 中使用自定义的 action 。

通过自定义 ad-hoc 使得用户可以频繁调用一个 action 而省去了重复写多个 action 的过程，关于如何定义和使用 ad-hoc action 可看这里。

 

注意，除了 system action 和 ad-hoc action，也可以自定义 action，将自定义 action 上传到 Mistral 即可在 workflow 中使用，关于如何自定义 action 可看这里。

4 Mistral API

Mistral 提供了多组 Rest API 供用户调用，如：

• GET /v2/workflows
• POST /v2/workflows
• DELETE /v2/workflows
• PUT /v2/workflows
• GET /v2/actions
• ...

通过 Mistral 命令行查看调用的 Rest API：

[root@lianhuasheng home]# mistral workflow-list --debug
DEBUG (connectionpool) Starting new HTTP connection (1): localhost:8989
DEBUG (connectionpool) http://localhost:8989 "GET /v2/workflows?fields=id%2Cname%2Cnamespace%2Cproject_id%2Ctags%2Cinput%2Cscope%2Ccreated_at%2Cupdated_at&sort_keys=created_at&sort_dirs=asc HTTP/1.1" 200 68369
DEBUG (httpclient) HTTP GET http://localhost:8989/v2/workflows?fields=id%2Cname%2Cnamespace%2Cproject_id%2Ctags%2Cinput%2Cscope%2Ccreated_at%2Cupdated_at&sort_keys=created_at&sort_dirs=asc 200
...

(看这里详细了解 Mistral Rest API)

5 Mistral 常用命令

Mistral 提供了一系列命令查看 workflow 的执行，执行 mistral 进入交互模式，输入 help 查看这些命令：

(mistral) help

Shell commands (type help <topic>):
===================================
alias  exit  history  py        quit  shell      unalias
edit   help  load     pyscript  set   shortcuts

Application commands (type help <topic>):
=========================================
action-create                environment-get       run-action
action-delete                environment-list      service-list
action-execution-delete      environment-update    task-get
action-execution-get         event-trigger-create  task-get-published
action-execution-get-input   event-trigger-delete  task-get-result
action-execution-get-output  event-trigger-get     task-list
action-execution-list        event-trigger-list    task-rerun
action-execution-update      execution-create      workbook-create
action-get                   execution-delete      workbook-delete
action-get-definition        execution-get         workbook-get
action-list                  execution-get-input   workbook-get-definition
action-update                execution-get-output  workbook-list
action-validate              execution-get-report  workbook-update
bash-completion              execution-list        workbook-validate
complete                     execution-update      workflow-create
cron-trigger-create          help                  workflow-delete
cron-trigger-delete          member-create         workflow-get
cron-trigger-get             member-delete         workflow-get-definition
cron-trigger-list            member-get            workflow-list
environment-create           member-list           workflow-update
environment-delete           member-update         workflow-validate

 

举个简单的示例查看 workflow 的执行情况(该示例来自这里)：

1) 自定义 workflow：

---
version: "2.0"

my_workflow:
  type: direct

  input:
    - names

  tasks:
    task1:
      with-items: name in <% $.names %>
      action: std.echo output=<% $.name %>
      on-success: task2

    task2:
      action: std.echo output="Done"

 

2) 上传 workflow 到 mistral：

$ mistral workflow-create <workflow.yaml>

+------------------------------------+-------------+-----------+--------+-------+---------------------+------------+
|ID                                  | Name        | Namespace | Tags   | Input | Created at          | Updated at |
+------------------------------------+-------------+-----------+--------+-------+---------------------+------------+
|9b719d62-2ced-47d3-b500-73261bb0b2ad| my_workflow |           | <none> | names | 2015-08-13 08:44:49 | None       |
+------------------------------------+-------------+-----------+--------+-------+---------------------+------------+

 

3) 运行 workflow：

$ mistral execution-create my_workflow '{"names": ["John", "Mistral", "Ivan", "Crystal"]}'

+--------------------+--------------------------------------+
| Field              | Value                                |
+--------------------+--------------------------------------+
| ID                 | 49213eb5-196c-421f-b436-775849b55040 |
| Workflow ID        | 9b719d62-2ced-47d3-b500-73261bb0b2ad |
| Workflow name      | my_workflow                          |
| Workflow namespace |                                      |
| Description        |                                      |
| Task Execution ID  | <none>                               |
| Root Execution ID  | <none>                               |
| State              | RUNNING                              |
| State info         | None                                 |
| Created at         | 2017-03-06 11:24:10                  |
| Updated at         | 2017-03-06 11:24:10                  |
+--------------------+--------------------------------------+

 

4) 检查 workflow 执行的状态：

$ mistral execution-get 49213eb5-196c-421f-b436-775849b55040    # 注意这里的 id 是 execution_id

+--------------------+--------------------------------------+
| Field              | Value                                |
+--------------------+--------------------------------------+
| ID                 | 49213eb5-196c-421f-b436-775849b55040 |
| Workflow ID        | 9b719d62-2ced-47d3-b500-73261bb0b2ad |
| Workflow name      | my_workflow                          |
| Workflow namespace |                                      |
| Description        |                                      |
| Task Execution ID  | <none>                               |
| Root Execution ID  | <none>                               |
| State              | SUCCESS                              |
| State info         | None                                 |
| Created at         | 2017-03-06 11:24:10                  |
| Updated at         | 2017-03-06 11:24:20                  |
+--------------------+--------------------------------------+

 

5) 检查 workflow 下 task 的执行情况：

$ mistral task-list 49213eb5-196c-421f-b436-775849b55040 

+--------------------------------------+-------+---------------+--------------------+--------------------------------------+---------+------------+---------------------+---------------------+
| ID                                   | Name  | Workflow name | Workflow namespace | Execution ID                         | State   | State info | Created at          | Updated at          |
+--------------------------------------+-------+---------------+--------------------+--------------------------------------+---------+------------+---------------------+---------------------+
| f639e7a9-9609-468e-aa08-7650e1472efe | task1 | my_workflow   |                    | 49213eb5-196c-421f-b436-775849b55040 | SUCCESS | None       | 2017-03-06 11:24:11 | 2017-03-06 11:24:17 |
| d565c5a0-f46f-4ebe-8655-9eb6796307a3 | task2 | my_workflow   |                    | 49213eb5-196c-421f-b436-775849b55040 | SUCCESS | None       | 2017-03-06 11:24:17 | 2017-03-06 11:24:18 |
+--------------------------------------+-------+---------------+--------------------+--------------------------------------+---------+------------+---------------------+---------------------+

 

检查 task 执行的输出：

$ mistral task-get-result f639e7a9-9609-468e-aa08-7650e1472efe

[
    "John",
    "Mistral",
    "Ivan",
    "Crystal"
]

 

6) 检查 task 下 action 的执行情况：

$ mistral action-execution-list f639e7a9-9609-468e-aa08-7650e1472efe   

+--------------------------------------+----------+---------------+--------------------+-----------+--------------------------------------+---------+----------+---------------------+---------------------+
| ID                                   | Name     | Workflow name | Workflow namespace | Task name | Task ID                              | State   | Accepted | Created at          | Updated at          |
+--------------------------------------+----------+---------------+--------------------+-----------+--------------------------------------+---------+----------+---------------------+---------------------+
| 4e0a60be-04df-42d7-aa59-5107e599d079 | std.echo | my_workflow   |                    | task1     | f639e7a9-9609-468e-aa08-7650e1472efe | SUCCESS | True     | 2017-03-06 11:24:12 | 2017-03-06 11:24:16 |
| 5bd95da4-9b29-4a79-bcb1-298abd659bd6 | std.echo | my_workflow   |                    | task1     | f639e7a9-9609-468e-aa08-7650e1472efe | SUCCESS | True     | 2017-03-06 11:24:12 | 2017-03-06 11:24:16 |
| 6ae6c19e-b51b-4910-9e0e-96c788093715 | std.echo | my_workflow   |                    | task1     | f639e7a9-9609-468e-aa08-7650e1472efe | SUCCESS | True     | 2017-03-06 11:24:12 | 2017-03-06 11:24:16 |
| bed5a6a2-c1d8-460f-a2a5-b36f72f85e19 | std.echo | my_workflow   |                    | task1     | f639e7a9-9609-468e-aa08-7650e1472efe | SUCCESS | True     | 2017-03-06 11:24:12 | 2017-03-06 11:24:17 |
+--------------------------------------+----------+---------------+--------------------+-----------+--------------------------------------+---------+----------+---------------------+---------------------+

 

检查 action 的执行结果：

$ mistral action-execution-get-output 4e0a60be-04df-42d7-aa59-5107e599d079

{
    "result": "John"
}