Actions

Action是一个具体的代码块，可以运用各种语言。

以下是一个简单的任务列表，可以通过Action实现：

1、重启一个服务在一台服务器上；

2、创建一个新的云主机；

3、确认Nagios发出的警报；

4、通过邮件或者短信发出报警信息；

5、通过IRC通道发出报警信息；

6、发送信息给slack；

7、快照虚拟机；

8、运行一个监控检测；

当具有匹配条件的规则被触发时，可以执行操作。可以将多个动作串联到一个工作流中。操作也可以通过CLI、API或UI直接从客户端执行。

Managing and Running Actions

在命令行下使用命令：

st2 action

st2action--help更多信息可以运行命令st2action -h例如：    st2actionlist -h

下面的命令展示了如何获取关于可用操作及其参数的信息的示例：

# Listallavailable actions (note that output may be lengthy)st2actionlist#listallactionsin"linux"packst2actionlist -p linux st2actionlist --packlinux#显示指定packlinux 下的动作check_loadavgst2actionget linux.check_loadavg#通过命令获取使用linux.check_loadavg动作的参数信息：st2 run linux.check_loadavg -h

手动执行action命令如下：

st2 run or st2 action execute

#Execute action immediately and display the results#立即执行并返回结果#通过core.http动作执行访问retail.belle.net.cn这个URL，直接输出返回值；st2runcore.http url="http://retail.belle.net.cn"#使用execute方式操作,进行计划执行st2 action execute core.http url="http://retail.belle.net.cn"#上述命令生成一个技术执行list，通过命令查询获取任务IDst2 executionlist-n1#获取执行结果st2 executionget5a5c60ffe138237e295d453f#在执行动作上增加时间标记st2runcore.localcmd=date--trace-tag="simple-date-check-`date +%s`"

Action Runners

Action是需要根据用户实现操作的执行环境。Stackstorm自带的action如SSH等，其目的是运行行动的作者实施而不是搭建环境。

Available Runners

action 是通过runner指定执行运行的，目前系统提供下列runner：

1、local-shell-cmd： 这个是一个本地runner，这个runner是在运行Stackstorm的服务器上执行linux命令；2、local-shell-script：这个是一个本地runner，action是通过脚本实现的，在Stackstorm运行的服务器运行脚本；3、remote-shell-cmd: 这个运行程序在用户提供的一个或多个远程主机上执行Linux命令;4、remote-shell-script: 远程在主机上执行脚本；5、python-script： 这个是一个Python的脚本，action通过Python的run()方法实现，在运行Stackstorm的服务器运行组件，通过run()返回一个元组成功的状态标志和结果对象。6、http-request： 执行http的action，通过http客户端访问返回http值；7、action-chain：这个runner是执行一个简单的工作流；8、mistral-v2： 这个是支持Openstack 的工作流runner；9、cloudslang： 这个是支持层cloudslang的工作流runner；10、inquirer： This runner providesthecore logicoftheInquiries feature.

Writing Custom Actions

Action 是有两部分组成：

1、yaml文件是Actions原数据的描述与它的输入；

2、实现Action动作的脚本；

如上所述，脚本需要遵循如下约定：（不限制语言类型）

1、脚本成功执行退出状态为0，异常执行退出状态为非零；

2、所有日志均采用标准输出；

Action Metadata

yaml文件是用于描述Action的行为动作定义。以下属性存在元数据中：

name - Action的名字

runner_type -  执行Action 的runner的类型

enable - Action是否可以被调用；

entry_point - Action运行脚本的所在目录路径：/opt/stackstorm/packs/${pack_name}/actions/

parameters - 描述元数据类型和默认值的参数字典。元数据是遵循JSON模式规范的结构化数据。常用参数类型含有 ‘string’ ，‘boolean’。‘number’（包含所有数字含小数等），‘object’，‘integer’（整数型）和 ‘array’。如果输入的参数正确可以执行Action，否则将跳过此Action

以下是一个简单的示例元数据文件，此文件类型是Python语言，通过Twilio web服务发送短信：

---name:"send_sms"runner_type:"python-script"description:"This sends an SMS using twilio."enabled:trueentry_point:"send_sms.py"parameters:    from_number:        type:"string"        description:"Your twilio 'from' number in E.164 format. Example +14151234567."        required:true        position:0    to_number:        type:"string"        description:"Recipient number in E.164 format. Example +14151234567."        required:true        position:1        secret:true    body:        type:"string"        description:"Body of the message."        required:true        position:2        default:"Hello {% if system.user %} {{ st2kv.system.user }} {% else %} dude {% endif %}!"

这个Action的runner是Python脚本。这个执行脚本send_sms.py与元数据在一个相同目录下。这个Action含有三个参数（from_number,to_number,body）

在上述例子中，to_number 参数的属性secret的值为true。如果一个属性被标记为secret，值将会记录在Stackstorm的服务日志中。

Parameters in Actions

在前一个的例子中，你可能会注意到你可以用st2kv.system前缀模板中的key-value存储参数。可以执行环境中的变量。例如：

parameters:user:type:"string"description:"User of this action."required: truedefault:"{{action_context.api_user}}"

action_context是环境中调用的变量。根据如何运行Action和Action的类型（简单或者工作流）来更改action_context的变量。

一个简单的执行的API只需要包含user和pack变量。执行触发的ChatOPS包含变量 api_user、user、pack和source_channel。在ChatOps中，api_user是Chatclient连接ChatOps的用户名，user是Stackstorm使用配置hubot的用户。source_channel 是接入ChatOps 命令集的通道。

除了action_context之外，通过config_context可以访问包含pack配置文件的key-value存储。在下面的例子中，如何给参数指定默认值：

---name:"send_sms"runner_type:"python-script"description:"This sends an SMS using twilio."enabled:trueentry_point:"send_sms.py"parameters:    from_number:        type:"string"        description:"Your twilio 'from' number in E.164 format. Example +14151234567."        required:false        position:0        default:"{{config_context.from_number}}"    to_number:        type:"string"        description:"Recipient number in E.164 format. Example +14151234567."        required:true        position:1        secret:true    body:        type:"string"        description:"Body of the message."        required:true        position:2        default:"Hello {% if system.user %} {{ st2kv.system.user }} {% else %} dude {% endif %}!"

在ActionChains 和工作流中，工作流中的每个任务/工作项都可以访问上一级的execution_id.

例如，一个Action chain的任务如下所示：

...-  name:"c2"  ref:"core.local"  parameters:    cmd:"echo \"c2: parent exec is {{action_context.parent.execution_id}}.\""on-success:"c3"on-failure:"c4"...

Action Registration

新注册一个Action：

1、将Action放置到指定目录；

2、告知系统此Action是可用的；

Actions 的包目录在 /opt/stackstorm/packs/。

一个action默认使用的是default pack，所以新创建的action的目录默认是在/opt/stackstorm/packs/default/actions。当测试完此action后，应该将其挪至专用pack；

创建一个指定action可以通过 命令  st2 action create my_action_metadata.yaml。重新加载所有action，使用 st2ctl reload --register-actions

Built-in Parameters （内置参数）

在配置元数据时，有些默认的内置参数可以至直接使用，也可以覆盖更改默认值实现各种runner：

args - (local-shell-script,remote-shell-script)  定义传递给cmd 变量名内命令的参数；

cmd - (local-shell-script,remote-shell-script) 配置在目标系统上运行的命令；

cwd - (local-shell-script,remote-shell-script) 配置执行远程命令所在目录；

env - (local-shell-script,local-shell-script-script,remote-shell-script,remote-shell-script,python-script)  可执行命令和脚本的环境变量；

dir - (local-shell-script , remote-shell-script) 配置在执行前将脚本从一个包复制到目标机器的目录。默认 /tmp。

Overriding Runner Parameters （覆盖参数）

runner的参数可以被覆盖。有的时候需要自定义或者优化action。

可以采取以下 linux.rsync action 导入linux的包；

通过linux.rsync action中的rsync命令 传递覆盖了cmd参数中的remote-shell-cmd属性。

---    name:'rsync'runner_type:'remote-shell-cmd'description:'Copy file(s) from one place to another w/ rsync'enabled:trueentry_point:''parameters:source:            type:'string'description:'List of files/directories to to be copied'required:truedest_server:            type:'string'description:"Destination server for rsync'd files"required:truedestination:            type:'string'description:'Destination of files/directories on target server'required:truecmd:immutable:truedefault:'rsync {{args}} {{source}} {{dest_server}}:{{destination}}'connect_timeout:            type:'integer'description:'SSH connect timeout in seconds'default:30args:description:'Command line arguments passed to rysnc'default:'-avz -e "ssh -o ConnectTimeout={{connect_timeout}}"'

参数的属性并不是所有都可以覆盖的，可重写属性如下：

default

description

enum

immutable

required

Environment Variables Available to Actions（用于action的环境变量）

默认情况下，本地、远程和Python运行程序为操作提供以下环境变量：

ST2_ACTION_PACK_NAME - 正在执行Action的所属包的名；

ST2_ACTION_EXCUTION_ID -正在执行Action 的操作ID；

ST2_ACTION_API_URL -  Action的API的URL；

ST2_ACTION_AUTH_TOKEN - Action的可用令牌；Action执行完成后，令牌自动失效；

下面本里shell脚本Action的例子中，描述如何使用可用环境变量：

#!/usr/bin/env bash# Retrieve a list of actions by hitting the API using cURL and the information provided# via environment variablesRESULT=$(curl -H"X-Auth-Token: ${ST2_ACTION_AUTH_TOKEN}"${ST2_ACTION_API_URL}/actions)echo${RESULT}

Converting Existing Scripts into Actions （将现有脚本转换成为Action）

将已有脚本转换成action按照以下步骤操作即可：

首先确保脚本符合约定

确保你的脚本执行成功的状态为0、失败为非零转态；

创建一个元数据文件

你需要创建一个元数据文件，它用于描述名称、描述、执行脚本的名字、和runner的参数；

当你转换脚本为action时，你需要执行local-shell-script或者remote-shell-script runner；

更新脚本中才参数

如果脚本不接受任何参数，可以跳过这步骤

      本地和远程脚本runnner 识别两类参数：

named - 这参数不包括position具体属性；

positional- 这参数包括position的具体属性；

      所有参数通过命令行状态传递给脚本。

      名称参数通过以下格式传递给脚本：

script.sh --param=value--param2=value--param3=value

    默认情况下，任何参数传递都要使用--，如果是使用-，可能一些参数没有对应前缀，你需要在元数据配置文件周工配置kwarg_op参数，如下：

---name:"my_script"runner_type:"remote-shell-script"description:"Script which prints arguments to stdout."enabled:trueentry_point:"script.sh"parameters:    key1:        type:"string"        required:true    key2:        type:"string"        required:true    key3:        type:"string"        required:true    kwarg_op:        type:"string"        immutable:true        default:"-"

在这个例子中，参数就可以通过以下方式传递：

script.sh-key1=value1-key2=value2-key3=value3

Posision参数通过以下格式传递至脚本：

script.sh value2 value1 value3

如果脚本只使用位置参数（这通常是现有脚本的情况），则只需在元数据文件中为位置属性的正确值声明参数。position参数规则如下下述描述：

string、integer，float - 序列字符串

boolean - 1为真、0为否

array - 序列为一个逗号分隔的字符串（eg  foo,bar,baz）

object - 序列json化

Stackstorm 通过空字符串“”代表一个没有默认值的参数如：

script.sh value1""value3

Example 1 - existing Bash script with positional arguments

send_to_syslog.sh是一个简单的shell脚本，通过命令行参数写入日志提供信息。

这个脚本具有两个参数：

1、日志系统服务器的地址；

2、写入信息；

#!/usr/bin/env bashSERVER=$1MESSAGE=$2logger-n${SERVER}${MESSAGE}

由于这个脚本使用position 参数，所以需要在元数据中定义它们：

---name:"send_to_syslog.log"runner_type:"remote-shell-script"description:"Send a message to a provided syslog server."enabled:trueentry_point:"send_to_syslog.sh"parameters:    server:        type:"string"        description:"Address of the syslog server"        required:true        position:0    message:        type:"string"        description:"Message to write"        required:true        position:1

上面代码中，我们声明了两个参数“server”和“message”。它们都声明一个位置属性（0是server，1是message），这意味着它们将作为位置参数传递给Action脚本，因此脚本不需要任何更改。

Writing Custom Python Actions

最简单的形式，一个Python的action是一个模块从st2actions.ruuners/pythonrunner.Action继承和实现run的方法。

Sample Python Action

Metadata file (my_echo_action.yaml):

---name:"echo_action"runner_type:"python-script"description:"Print message to standard output."enabled:trueentry_point:"my_echo_action.py"parameters:    message:        type:"string"        description:"Message to print."        required:true        position:0

Action script file (my_echo_action.py):

importsysfromst2actions.runners.pythonrunnerimportActionclassMyEchoAction(Action):    def run(self,message):        print(message)        if message == 'working':            return (True,message)        return (False,message)

这个Python的action将message信息打印到标准输出。用户提供的操作参数作为关键字参数传递给run方法。run方法执行完成后，返回的值和方法（任何值：布尔，字符串，列表，字典，等）被认为是其结果。如果出现异常将执行失败；

指定执行状态的另一种方法是返回带有两个项的元组：第一个项目是一个布尔指示状态，第二项是结果本身。

例如：

return false 如果被执行成功将返回“False”，return(False,"Falsed!") 如果执行失败将返回“Falsed！”的结果。

在上面的示例中，如果传递给action的message参数有效，则该操作将被视为成功（表示操作状态为true的结果中的第一个标志）。如果传入另一条消息，则操作将被视为失败（表示操作状态为false的结果元组中的第一个标志）。

更复杂的例子，可请阅读 actions in the Libcloud pack in StackStorm Exchange.

Configuration File

配置文件用配置“静态”不做改变的参数

对于用户自己定义或者更改的值的参数，应该在元数据文件中配置。

Python可以在整个配置文件中配置，这个是针对pack全局的。配置文件的名为.yaml  存储在目录/opt/stackstorm/configs/

配置文件是YAML格式。配置通过config参数自动解析并传递给Action构造类函数

Logging

日志里面的所有动作要通过记录器是具体的行动，可通过self.logger类属性进行。

这个记录是从测井模块标准Python记录器所以记录器方法象预期的那样工作（如logger.debug，logger.info，等）。

例如：

defrun(self):    ...    success = call_some_method()ifsuccess:self.logger.info('Action successfully completed')else:self.logger.error('Action failed...')

Action Service

Action serice 是通过提供一个公共方法提供不同的服务。现在支持数据存储方式。Action可以通过数据库来提取执行之间的任意数据。

The action service provides the same datastore management methods as the ones available on the sensor service. 

例如：（JSON格式。）

defrun(self):  data = {'somedata':'foobar'}# Add a value to the datastoreself.action_service.set_value(name='cache', value=json.dumps(data))# Retrieve a valuevalue =self.action_service.get_value('cache')  retrieved_data = json.loads(value)# Retrieve an encrypted valuevalue =self.action_service.get_value('ma_password', decrypt=True)  retrieved_data = json.loads(value)# Delete a valueself.action_service.delete_value('cache')

Pre-defined Actions（预先定义的Action）

Stackstorm中有部分预先定义的Action。这些Action在core包中：

core.local

这个Action是可以执行linux下shell的命令。可以直接在命令行下执行，例如：

st2 run core.localcmd='ls-l'

core.remote 

这个Action是可以在远程主机上执行linux命令，例如：

st2 run core.remote cmd='ls -l'hosts='host1,host2'username='user1'

core.http

这个Action是访问http的返回值。例如curl执行：

st2 run core.http url="http://httpbin.org/get"method="GET"

基于http登录，需要用户名和密码的基本认证

st2 run core.http url="http://httpbin.org/get"method="GET"username=user1 password=passwd1

To see all actions in the core pack:

st2actionlist --pack=core