Puppet Module

If you’re ready to take complete control of your StackStorm instances, then the stackstorm-st2 Puppet module is for you! It offers repeatable, configurable, and idempotent production-friendly StackStorm installations.

The stackstorm-st2 Puppet module is available on Puppet Forge: stackstorm-st2

Source code for the module is available as a GitHub repo: StackStorm/puppet-st2

Contents

Supported Platforms
Quick Start
Classes
Resource Types
Installing and Configuring Packs
Configuring Authentication
Configuring ChatOps
Configuring Key/Value pairs

Supported Platforms 

The Puppet module supports the same platforms as manual installation, i.e.:

Ubuntu Trusty (14.04)
Ubuntu Xenial (16.04)
RHEL 7/CentOS 7
RHEL 8/RockyLinux 8/CentOS 8

Note

StackStorm is verified on RHEL/RockyLinux 8.x distributions, but our RPMs should be compatible with other RHEL``8.x`` derivatives, e.g. CentOS 8 Stream.

The same system size requirements also apply.

Quick Start 

The first step is installing Puppet, for this please consult the official Puppet installation documentation

Note

Puppet versions <= 3.x are no longer supported. Please utilize Puppet >= 4.

To get started with a single node deployment, and default configuration settings, we’re going to install the stackstorm-st2 module and its dependencies, then tell Puppet to perform a full install of StackStorm. In order to accomplish this, run the following commands as root:

puppet module install stackstorm-st2
puppet apply -e "include ::st2::profile::fullinstall"

Note

The default StackStorm login credentials according to https://github.com/StackStorm/puppet-st2/blob/master/manifests/params.pp are: st2admin:Ch@ngeMe. Don’t forget to change them.

Classes 

::st2::profile::fullinstall is the quick and easy way to get StackStorm up and running. The stackstorm-st2 module provides numerous additional classes in order to configure StackStorm just the way you like it. Below is a list of classes available for configuration:

::st2 - The main configuration point for the StackStorm installation.
::st2::profile::client - Profile to install all client libraries for StackStorm
::st2::profile::fullinstall - Full installation of StackStorm and dependencies
::st2::profile::mongodb - StackStorm configured MongoDB installation
::st2::profile::nodejs - StackStorm configured NodeJS installation
::st2::profile::python - Python installed and configured for StackStorm
::st2::profile::rabbitmq - StackStorm configured RabbitMQ installation
::st2::proflle::server - StackStorm server components
::st2::profile::web - StackStorm WebUI components
::st2::profile::chatops - StackStorm chatops components

Resource Types 

Along with the configuration classes, there are a number of defined resources provided that allow installation and configuration of StackStorm’s components.

::st2::auth_user - Configures a user (and password) in flat_file auth
::st2::kv - Defines a key/value pair in the StackStorm datastore
::st2::pack - Installs and configures a StackStorm pack
::st2::user - Configures a system-level (linux) user and SSH keys

Installing and Configuring Packs 

StackStorm packs can be installed and configured directly from Puppet. This can be done via the ::st2::pack and st2::pack::config defined types.

Installation/Configuration via Manifest:

# install pack from the exchange
st2::pack { 'linux': }

# install pack from a git URL
st2::pack { 'private':
  repo_url => 'https://private.domain.tld/git/stackstorm-private.git',
}

# install pack and apply configuration
st2::pack { 'slack':
  config   => {
    'post_message_action' => {
      'webhook_url' => 'XXX',
    },
  },
}

Installation/Configuration via Hiera:

st2::packs:
  linux:
    ensure: present
  private:
    ensure: present
    repo_url: https://private.domain.tld/git/stackstorm-private.git
  slack:
    ensure: present
    config:
      post_message_action:
        webhook_url: XXX

Configuring Authentication 

StackStorm uses a pluggable authentication system where authentication is delegated to an external service called a “backend”. The st2auth service can be configured to use various backends. Note only one is active at any one time. For more information on StackStorm authentication see the authentication documentation.

The following backends are currently available:

flat_file - Authenticates against an htpasswd file (default). See the flat-file backend documentation
keystone - Authenticates against an OpenStack Keystone service See the keystone backend documentation
ldap - Authenticates against an LDAP server such as OpenLDAP or Active Directory . See the LDAP backend documentation
mongodb - Authenticates against a collection named users in MongoDB. See the MongoDB backend
pam - Authenticates against the PAM Linux service. See the PAM backend documentation

By default the flat_file backend is used. To change this you can configure it when instantiating the ::st2 class in a manifest file:

Configuration via Manifest:

class { '::st2':
  auth_backend => 'ldap',
}

Configuration via Hiera:

st2::auth_backend: ldap

Each backend has their own custom configuration settings. The settings can be found by looking at the backend class in the manifests/st2/auth/ directory. These parameters map 1-for-1 to the configuration options defined in each backend’s GitHub page (links above). Backend configurations are passed in as a hash using the auth_backend_config option. This option can be changed when instantiating the ::st2 class in a manifest file:

Configuration via Manifest:

class { '::st2':
  auth_backend        => 'ldap',
  auth_backend_config => {
    ldap_uri      => 'ldaps://ldap.domain.tld',
    bind_dn       => 'cn=ldap_stackstorm,ou=service accounts,dc=domain,dc=tld',
    bind_pw       => 'some_password',
    ref_hop_limit => 100,
    user          => {
      base_dn       => 'ou=domain_users,dc=domain,dc=tld',
      search_filter => '(&(objectClass=user)(sAMAccountName={username})(memberOf=cn=stackstorm_users,ou=groups,dc=domain,dc=tld))',
      scope         => 'subtree'
    },
  },
}

Configuration via Hiera:

st2::auth_backend: ldap
st2::auth_backend_config:
  ldap_uri: "ldaps://ldap.domain.tld"
  bind_dn: "cn=ldap_stackstorm,ou=service accounts,dc=domain,dc=tld"
  bind_pw: "some_password"
  ref_hop_limit: 100
  user:
    base_dn: "ou=domain_users,dc=domain,dc=tld"
    search_filter: "(&(objectClass=user)(sAMAccountName={username})(memberOf=cn=stackstorm_users,ou=groups,dc=domain,dc=tld))"
    scope: "subtree"

Configuring ChatOps 

stackstorm-st2 can manage the ChatOps configuration of your StackStorm installation. We provide support for configuring all Hubot settings, installing custom ChatOps adapters, and configuring all adapter settings.

Configuration via Manifest:

class { '::st2':
  chatops_hubot_alias  => "'!'",
  chatops_hubot_name   => '"@RosieRobot"',
  chatops_api_key      => '"xxxxyyyyy123abc"',
  chatops_web_url      => '"stackstorm.domain.tld"',
  chatops_adapter      => {
    hubot-adapter => {
      package => 'hubot-rocketchat',
      source  => 'git+ssh://[email protected]:npm/hubot-rocketchat#master',
    },
  },
  chatops_adapter_conf => {
    HUBOT_ADAPTER        => 'rocketchat',
    ROCKETCHAT_URL       => 'https://chat.company.com:443',
    ROCKETCHAT_ROOM      => 'stackstorm',
    LISTEN_ON_ALL_PUBLIC => true,
    ROCKETCHAT_USER      => 'st2',
    ROCKETCHAT_PASSWORD  => 'secret123',
    ROCKETCHAT_AUTH      => 'password',
    RESPOND_TO_DM        => true,
  },
}

Configuration via Hiera:

# character to trigger the bot that the message is a command
# example: !help
st2::chatops_hubot_alias: "'!'"

# name of the bot in chat, sometimes requires special characters like @
st2::chatops_hubot_name: '"@RosieRobot"'

# API key generated by: st2 apikey create
st2::chatops_api_key: '"xxxxyyyyy123abc"'

# Public URL used by ChatOps to offer links to execution details via the WebUI.
st2::chatops_web_url: '"stackstorm.domain.tld"'

# install and configure hubot adapter (rocketchat, nodejs module installed by ::nodejs)
st2::chatops_adapter:
  hubot-adapter:
    package: 'hubot-rocketchat'
    source: 'git+ssh://[email protected]:npm/hubot-rocketchat#master'

# adapter configuration (hash)
st2::chatops_adapter_conf:
  HUBOT_ADAPTER: rocketchat
  ROCKETCHAT_URL: "https://chat.company.com:443"
  ROCKETCHAT_ROOM: 'stackstorm'
  LISTEN_ON_ALL_PUBLIC: true
  ROCKETCHAT_USER: st2
  ROCKETCHAT_PASSWORD: secret123
  ROCKETCHAT_AUTH: password
  RESPOND_TO_DM: true

Configuring Key/Value pairs 

The puppet type ::st2::kv can manage key/value pairs in the StackStorm datastore:

Configuring via Manifests:

st2::kv { 'my_key_name':
  value => 'SomeValue',
}

st2::kv { 'another_key':
  value => 'moreData',
}

Configuration via Hiera:

st2::kvs:
  my_key_name:
    value: SomeValue
  another_key:
    value: moreData