Errbot meets StackStorm in Slack

“An exuberating look at purple lightning shooting down from a cloud into the city of Twin Peaks” by Emil Jarfelt on Unsplash

In previous article we covered how StackStorm automation platform combined with Errbot, a chat bot, could speed up our efforts to introduce ChatOps in an organization. Now we are going to walk through the preparation of local development environment, where we will experiment with and enhance our very own chat bot. Within the team, we collaborate daily in Slack as our main chat service.

These days Docker is used by almost everyone.

We assume that our reader is familiar with basics of Linux command line (GNU Bash), Git, GNU Make, Docker and docker-compose. We have tested following instructions on CentOS Linux 7 and Debian GNU/Linux 9 “stretch”. However, if you work on MacOS X or Windows, everything should look pretty the same. You just need to have tools mentioned above installed.

Minimum required versions are:

• Docker 1.13.1 (or later Docker CE)
• docker-compose 1.17.1

Our deployment will be completely based on publicly available Docker containers. This is a high-level architecture:

We must emphasize, that we’re going to prepare local test and development environment. Many steps would be purposely simplified. It is not intended to use as is in production. Infrastructure specifics, security and reliability concerns should be considered before live deployment. This is a guidance, not a turn-key solution. We will provide more explanations on questionable points.

With that said, let’s get started.

First, we need to clone st2-docker repository from GitHub.

git clone https://github.com/StackStorm/st2-docker.git
cd st2-docker

Next, we must to generate environment variable files, which would contain users and passwords for dependent services: MongoDB, PostgreSQL, RabbitMQ, Redis and StackStorm itself. We will not use the credentials directly, but that is required for starting up our containers.

make env

After that, we are able to pull container images from Docker Hub and start the services in a background.

docker-compose up -d

All StackStorm services are running in a single container.

However, it is possible to run one ST2 process per container or even deploy to Kubernetes. We use a single container layout setup for the sake of simplicity.

Make Errbot first-class citizen for StackStorm.

Now we need to arrange necessary configurations in StackStorm for Errbot to be able to reach ST2 API and receive events back asynchronously. We will enter the container and perform changes there directly in the shell.

All modifications we do within the container will persist.

The containers declared in docker-compose.yml file in the st2-docker git repository is going to have named volumes attached. So, all changes in the packs and configuration files should be saved even if you delete the containers or pull the latest version. That’s how you might do an upgrade of your development environment afterwards.

You simply run the command:

docker-compose exec stackstorm bash

That gives you an interactive shell with root privileges inside the stackstorm service container.

First off, let’s generate an API key for Errbot:

st2 apikey create -k -m '{"used_by": "my Errbot"}'

Save the key it has returned, we will put it in the special variable later.

The API key was created for st2-admin user.

The st2-admin user is full privileged account in StackStorm. That is convenient for local development and testing, but you should consider creating separate user with more strict permissions.

Then we need to reconfigure chatops pack to talk back to Errbot, instead of Hubot configured by default. Check that the pack is already there:

st2 pack list -a name
+---------+
| name    |
+---------+
| chatops |
| core    |
| default |
| linux   |
| packs   |
+---------+

We’ve got it. If it is not in the list, just install it:

st2 pack install chatops

Turn off notification rule for Hubot:

cd /opt/stackstorm/packs/chatops/rules/
sed -i -e '/^enabled: / s/true/false/' notify_hubot.yaml

Create a rule for Errbot instead:

wget https://raw.githubusercontent.com/fmnisme/err-stackstorm/master/contrib/stackstorm-chatops/rules/notify_errbot.yaml

Change post_message action to use the new rule:

cd ../actions
sed -i -e '/^\s\+default: / s/chatops/errbot/' post_message.yaml

Finally, apply the configuration changes:

st2ctl reload

To exit the container just press Ctrl+D.

It is time to create a bot integration in Slack.

1. Go to team menu, select Customize Slack option.
2. In Customize Your Workspace page menu, click on Configure Apps.
3. Select Custom Integrations and then Bots.
4. Create new integration. Depending on a Slack team settings, you may need to issue a Request to Install a bot from Slack Workspace Owner.
5. Copy the API token, we will need it to configure our Errbot.
6. Give your new bot a fun name and describe what it does.
7. Press Save Integration.

Now you have a new team member. Need to make it alive!

Now we need to get Errbot container.

Clone this Git repository to be able to spin up pre-configured Errbot using docker-compose.

git clone https://github.com/vutny/errbot-slack-st2.git
cd errbot-slack-st2

Remember the API token generated during the creation of the Slack integration? We save it in the environment variable:

export BOT_TOKEN='xoxb-123456789098-QwErTyUiOpaSdFgHjKlZxCvB'

Also, you need to specify bot admins to be able to manage the bot itself.

export BOT_ADMINS='@denys'

We assume that Errbot and StackStorm containers are running on a single machine.

The StackStorm container publishes 443 (https) port on all host interfaces by default, so you could reach it from other hosts. We use Docker bridge loopback IP address (172.17.0.1) for Errbot to communicate to ST2. That works on most GNU/Linux systems out of the box, but on others it could be different. Try the following command to find out:

ip address show dev docker0

Docker for MacOS binds published port from containers on 192.168.65.1 virtual address. You will need to customize StackStorm endpoint in this case. The host IP address or FQDN could be used, if it doesn’t change too often. Set the variable like this:

export ST2_HOST=192.168.65.1

You may dive deep into the Docker networking to discover other ways of connecting containers.

At last, you must specify the API key for accessing StackStorm, that we have created above:

export ST2_API_KEY='MGU5NjQ2YzM2NzgwNDQxNmQ2MjI1ZjJkNzZlMGNlYm...'

Everything is set and done. The Bot is ready to be deployed.

docker-compose up -d

Now you’re able to send direct messages to the bot via special Apps channel list in Slack. Click on Browse Apps and find your bot if it is not already there.

The bot should respond to the !status command:

Awaiting your command

We should see that Errbot’s internal web server has been configured to receive event streams back from StackStorm. Check that the bot has detected Action Aliases by asking this:

!st2help

We should see:

Robots to the rescue

Now we could partially administer StackStorm via chat, for example, check out some new packs to add:

!st2 pack search aws

Let me google it for you, human

When you will be ready to share the bot with your team to fully enable ChatOps, better to disable aliases from the example and pack packs in ST2 and add your own ones. In our next article we will cover the creation of the custom pack with some useful commands for the bot.