Ansible-st2

Ansible roles and playbooks to deploy StackStorm.

StackStorm is event-driven automation platform written in Python. With over 50+ integrations like GitHub, Docker, Nagios, NewRelic, AWS, Ansible it allows you to wire together your existing infrastructure into complex Workflows with auto-remediation and many more. Aka IFTTT orchestration for Ops.

Supported platforms

• Ubuntu Focal (20.04)
• RHEL 7 and CentOS 7
• RHEL 8 and Rocky Linux 8

If you are using the provided Vagrantfile, note that it uses Focal by default.

In order to access StackStorm Web UI, please do not forget to ensure that the http and https ports are allowed by the firewall.

Requirements

A supported version of Ansible and its dependencies. At least 2 GB of memory and 3.5 GB of disk space is required, since StackStorm is shipped with RabbitMQ, Mongo, Redis and nginx.

Installation

# Deploy StackStorm
ansible-playbook stackstorm.yml

Variables

Below is the list of variables which you can redefine in your playbook, or inventory, to customize the StackStorm deployment:

Variable	Default	Description
st2repo
st2repo_name	stable	StackStorm PackageCloud repository to install. stable, unstable, staging-stable, staging-unstable
st2
st2_version	latest	StackStorm version to install. present to install available package, latest to get automatic updates, or pin it to numeric version like 2.2.0 or with revision like 2.2.0-1
st2_config	{}	Hash with StackStorm configuration settings to set in st2.conf ini file.
st2_system_user	stanley	System user from which st2 will execute local/remote shell actions.
st2_system_user_in_sudoers	yes	Add st2_system_user to the sudoers (recommended for most st2 features to work).
st2_ssh_key_file	/home/{{st2_system_user}}/.ssh/{{st2_system_user}}_rsa	Path to st2_system_user SSH private key. It will be autogenerated by default.
st2_auth_enable	yes	Enable StackStorm standalone authentication.
st2_auth_username	testu	Username used by StackStorm standalone authentication.
st2_auth_password	testp	Password used by StackStorm standalone authentication.
st2_save_credentials	yes	Save credentials for local CLI in /root/.st2/config file.
st2_rbac_enable	no	Enable RBAC.
st2_rbac	See st2_rbac variable in role defaults	RBAC roles and assignments. This is a dictionary with three keys roles, assignments, and mappings (based on LDAP group membership). roles, assignments, and mappings are arrays. Each element in the array follows the exact YAML schema for roles, assignments defined in ST2 documentation. mappings are slightly different, they use a name and a mapping key, see ./roles/StackStorm.st2/defaults/main.yml for an example.
st2_ldap_enable	no	Enable LDAP authentication backend.
st2_ldap	See st2_ldap variable in role defaults	Settings for LDAP authentication backend. st2_ldap is a dictionary and has one item backend_kwargs. backend_kwargs should be provided as exactly listed in ST2 documentation for LDAP configuration.
st2_packs	[ st2 ]	List of packs to install. This flag does not work with a --python3 only pack.
st2_python_packages	[ ]	List of python packages to install into the /opt/stackstorm/st2 virtualenv. This is needed when deploying alternative auth or coordination backends which depend on Python modules to make them work.
st2web
st2web_version	latest	st2web version to install. present to install available package, latest to get automatic updates, or pin it to numeric version like 2.2.0 or with revision like 2.2.0-1.
st2web_ssl_certificate	null	String with custom SSL certificate (.crt). If not provided, self-signed certificate will be generated.
st2web_ssl_certificate_key	null	String with custom SSL certificate secret key (.key). If not provided, self-signed certificate will be generated.
st2web_nginx_config	null	String with a custom nginx configuration file (st2.conf). If not provided, the default st2.conf will be used.
st2chatops
nodejs_major_version	14	The default fits st2chatops version >= 3.5.0.
st2chatops_version	latest	st2chatops version to install. present to install available package, latest to get automatic updates, or pin it to numeric version like 2.2.0 or with revision like 2.2.0-1.
st2chatops_st2_api_key		st2 API key to be updated in st2chatops.env using "st2 apikey create -k" in a task
st2chatops_hubot_adapter		Hubot Adapter to be used for st2chatops. Default is shell, but should be changed to one of the supported adapters.[Required]
st2chatops_config	{ }	Based on adapter in st2chatops_hubot_adapter, provide hash for the adapter settings, to update st2chatops.env. For example, for Slack hubot adapter: st2chatops_config: HUBOT_SLACK_TOKEN: xoxb-CHANGE-ME-PLEASE
st2chatops_version	latest	st2chatops version to install. Use latest to get automatic updates or pin it to numeric version like 2.2.0.

Examples

Install latest stable StackStorm with all its components on local machine:

ansible-playbook --inventory localhost, --connection local stackstorm.yml

To install StackStorm on a remote machine named stackstorm.example.com, create and reference an inventory:

echo "stackstorm.example.com" > inventory
ansible-playbook --inventory inventory stackstorm.yml

Keeping the latest version is useful to update StackStorm by re-running the playbook, since it will reinstall (upgrade) st2 when there is new version available.

This is default behavior. If you do not want updates, consider pinning specific version and revision numbers.

Install a specific version of st2 with pinned revision number:

ansible-playbook stackstorm.yml --extra-vars "st2_version=2.2.0 st2_revision=8"

Installing behind a proxy

If you are installing from behind a proxy, you can use environment variables http_proxy, https_proxy, and no_proxy in the playbook. For the st2smoketests, you will need to disable proxy for localhost.

environment:
  http_proxy: http://proxy.example.net:3128
  https_proxy: http://proxy.example.net:3128
  no_proxy: 127.0.0.1,localhost

Development

There are a few requirements when developing on ansible-st2.

These are the platforms we must support (must pass end-to-end testing):

• Ubuntu Focal (20.04)
• CentOS 7
• Rocky Linux 8
• RHEL 7 (via AWS)
• RHEL 8 (via AWS)

The playbooks and roles must support Ansible idempotence. That is, re-running the stackstorm.yml playbook must end with the result changed=0.*failed=0 (provided that versions and revisions are pinned).

For local development, there is a Vagrantfile available. By default, the following command will set up an ubuntu20 box (ubuntu/focal64):

vagrant up

Other supported distributions:

vagrant up ubuntu20
vagrant up centos7
vagrant up rockylinux8

Other installation methods

You may be interested in other methods to deploy StackStorm:

• Configuration Management

  • Puppet Module

• Manual Instructions

  • Ubuntu Bionic (18.04)
  • Ubuntu Focal (20.04)
  • RHEL 8 / Rocky Linux 8
  • RHEL 7 / CentOS 7

Getting help

If you encounter any problems, our community is ready to help, feel free to:

• Ask questions in our public Slack channel
• Report issues, provide feature requests, or just give this project a ✮ star

Your questions, comments, and contributions are more than welcome and greatly appreciated!