Quick Start

Got StackStorm installed? Enjoyed the intro video? Let’s give it a try. This guide will walk you through StackStorm basics and help you build and run a simple automation: a rule that triggers an action on external event.

Explore StackStorm with CLI

The best way to explore StackStorm is to use CLI. Start by firing a few commands:

st2 --version
# Get help. It's a lot. Explore.
st2 -h
# List the actions from a 'core' pack
st2 action list --pack=core
st2 trigger list
st2 rule list
# Run a local shell command
st2 run core.local -- date -R
# See the execution results
st2 execution list
# Fire a shell comand on remote hosts. Requires passwordless SSH configured.
st2 run core.remote hosts='localhost' -- uname -a

The default “all-in-one” installation deploys the CLI along with the StackStorm services. CLI can be used to access StackStorm service remotely. All StackStorm operations are also available via REST API and Python bindings. Check the CLI and Python Client reference for details.

Work with Actions

StackStorm comes with a several generic actions out of the box. Action Library can be easily extended by getting actions from the community or consuming your existing scripts (more on that later). Browse Action Library with st2 action list. Action is called by ref as pack.action_name (e.g. core.local). Learn about an action by doing st2 action get <action>, or, st2 run <action> --h ( --help): it shows description along with action parameters so that you know how to run it from the CLI or use it in rules and workflows.

# List all the actions in the library
st2 action list
# Get action metadata
st2 action get core.http
# Display action details and parameters.
st2 run core.http --help

To run the action from the CLI, do st2 run <action> key=value positional arguments.

# Run a local command
st2 run core.local -- uname -a

# HTTP REST call to st2 action endpoint
st2 run -j core.http url="http://localhost:9101/v1/actions" method="GET"

Use core.remote action to run linux command on multiple hosts over ssh. This assumes that passwordless SSH access is configured for the hosts, as described in Configure SSH section.

st2 run core.remote host='abc.example.com, cde.example.com' user='mysshuser' -- ls -l

Note

For core.local and core.remote actions, we use -- to separate action parameters to ensure that options keys, like -l or -a are properly passed to the action. Alternatively, core.local and core.remote actions take the cmd parameter to pass crazily complex commands.

When specifying a command using the command line tool, you also need to escape all the variables, otherwise the variables will get interpolated locally by a shell. Variables are escaped using a backslash (\) - e.g. \$user.

# Using `--` to separate arguments
st2 run core.local -- ls -al
# Equivalent using `cmd` parameter
st2 run core.local cmd="ls -al"
# Crasily complex command passed with `cmd`
st2 run core.remote hosts='localhost' cmd="for u in bob phill luke; do echo \"Logins by \$u per day:\"; grep \$u /var/log/secure | grep opened | awk '{print \$1 \"-\" \$2}' | uniq -c | sort; done;"

Check the action execution history and details of action executions with st2 execution command:

# List of executions (recent at the bottom)
st2 execution list
# Get execution by ID
st2 execution get <execution_id>
# Get the output of just the last execution
st2 execution list -n 1

That’s it. You have learned to use StackStorm‘s action library. Let’s proceed to automations.

Define a Rule

StackStorm uses rules to fire actions or workflows when events happen. Events are typically monitored by sensors. When a sensor catches an event, it fires a trigger. Trigger trips the rule, the rule checks the criteria and if it matches, it runs an action. Easy enough. Let’s look at an example.

Sample rule: sample_rule_with_webhook.yaml :

---
    name: "examples.webhook_file"
    description: "Sample rule dumping webhook payload to a file."
    enabled: true

    trigger:
        type: "core.st2.webhook"
        parameters:
            url: "sample"

    criteria:
        trigger.body.name:
            pattern: "st2"
            type: "equals"

    action:
        ref: "core.local"
        parameters:
            cmd: "echo \"{{trigger.body}}\" >> /tmp/st2.webhook_sample.out"

The rule definition is a YAML spec with thee sections: trigger, criteria, and action. It configures the webhook trigger with url, applies filtering criteria based trigger parameters. This one configures a webhook with sample sub-url so it listens on http://{host}:9101/v1/webhooks/sample. When it fires, it appends a payload to the file, only if the name value in payload is st2. See Rules for detailed rule anatomy.

Trigger payload is referred with {{trigger}}. If trigger payload is valid JSON, it is parsed and can be accessed like {{trigger.path.to.parameter}} (it’s Jinga template syntax).

While the most data are retrieved as needed by StackStorm, you may need to store and share some common variables. Use StackStorm datastore service to store the values and reference them in rules and workflows as {{system.my_parameter}}. This creates user=stanley key-value pair:

st2 key create user stanley
st2 key list

What are the triggers availabe to use in rules? Just like with actions, use the CLI to browse triggers, learn what the trigger does, how to configure it, and what is it’s payload structure:

# List all available triggers
st2 trigger list

# Check details on Interval Timer trigger
st2 trigger get core.st2.IntervalTimer

# Check details on the Webhook trigger
st2 trigger get core.st2.webhook

Deploy a Rule

StackStorm can be configured to auto-load the rules, or they are deployed with API or CLI:

st2 rule create /usr/share/doc/st2/examples/rules/sample_rule_with_webhook.yaml
st2 rule list
st2 rule get examples.webhook_file

Once the rule is created, the webhook begins to listen on http://{host}:9101/v1/webhooks/{url}. Fire the post, check out the file and see that it appends the payload if the name=Joe.

# Post to the webhook
curl http://localhost:9101/v1/webhooks/sample -d '{"foo": "bar", "name": "st2"}' -H 'Content-Type: application/json'
# Check if the action got executed (this shows last action)
st2 execution list -n 1
# Check that the rule worked
tail /tmp/st2.webhook_sample.out
# And for fun, same post with |st2|
st2 run core.http method=POST body='{"you": "too", "name": "st2"}' url=http://localhost:9101/v1/webhooks/sample
# Check that the rule worked again
tail /tmp/st2.webhook_sample.out

Congratulations, your first StackStorm rule is up and running!

Basic examples of rules, along with sample actions and sensors can be found at /usr/share/doc/st2/examples/. To get them deployed, copy them to /opt/stackstorm/packs/ and reload the content by running st2 run packs.load. For more content examples checkout st2contrib community repo on GitHub.

Troubleshooting

If something goes wrong:

  • Check recent executions: st2 execution list
  • Check the logs at /var/log/st2.
  • Use service control st2ctl to check service status, restart services, reload packs, or clean the db.
  • Engage with developers

What’s Next?

Questions? Problems? Suggestions? Engage!