Skip to content

Instantly share code, notes, and snippets.

@jfryman

jfryman/chatops.md Secret

Last active August 29, 2015 14:19
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save jfryman/deeabda77813dae7c458 to your computer and use it in GitHub Desktop.
Save jfryman/deeabda77813dae7c458 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
chatops.md

Hi, and thanks for helping us try out our private ChatOps beta. We value your feedback, and would love to hear it. Please send us a note at support@stackstorm.com, or come chat with us on IRC at irc://irc.freenode.net/#stackstorm.

What is ChatOps

ChatOps is a new operational paradigm where work that is already happening in the background today is brought into a common chatroom. By doing this, you are unifying the communication about what work should get done with actual history of the work being done. Things like deploying code from chat, viewing graphs from a TSDB or logging tool, or creating new Jira tickets... all of these are examples of tasks that can be done via ChatOps.

Not only does ChatOps reduce the feedback loop of work output, it also empowers others to accomplish complex self-service tasks that they otherwise would not be able to do. Combining ChatOps and StackStorm is an ideal combination, where from Chat users will be able to execute actions and workflows to accelerate the IT delivery pipeline.

Excited to try it out? Let's do it!

Getting Started

In effort to make setup as quick and easy as possible, we have setup our st2workroom environment to allow you to spin up a test copy of StackStorm with ChatOps to kick the tires around. This installation has all of the necessary bits configured, including basic Hubot and Pack deployment management. Once this is done, we need to configure the workroom to download the most up-to-date code. Next, we'll configure HuBot to connect to your Chat Room and StackStorm. Finally, we'll show you how to enable start setting up ChatOps actions.

Common Setup

Regardless if you use the Vagrant test environment, or install manually, you will need to provide us with a:

  • GitHub account with SSH key added

Also, send us the name of the GitHub user account that you will be using to test out our ChatOps. This is a private project for now, and we will need to add you to our Early Access Feedback group. Generate a SSH key, and attach it to this account. This is how you will access the Hubot ChatOps adapter.

Vagrant Setup

To get started, you will need a few software projects. They are:

This project is used to help provide a consistent experience for people testing, experimenting, developing with, or developing against StackStorm. For more info on this project and how it is used, please take a look at http://stackstorm.com/2015/04/03/rapid-integration-development-with-stackstorm/.

To get started, first download the st2workroom.

$ mkdir ~/stackstorm
$ git clone https://github.com/StackStorm/st2workroom ~/stackstorm/st2workroom
$ cd ~/stackstorm/st2workroom

Then, let's configure the workroom. We'll first configure the stack. This defines where StackStorm will look for its integration packs. Open up the file stacks/st2.yaml with your favorite editor. You should configure it to look like this:

# stacks/st2.yaml
---
# Defaults can be defined and reused with YAML anchors
defaults: &defaults
  domain: stackstorm.net
  memory: 1024
  cpus: 1
  box: puppetlabs/ubuntu-14.04-64-puppet
st2express:
  <<: *defaults
  hostname: st2express
  private_networks:
    - 172.168.200.10
  sync_type: nfs
  puppet:
    facts:
      role: st2express
  mounts:
    - "/opt/stackstorm:artifacts/stackstorm"

This will setup StackStorm to store all pack files and chatops aliases in the artifacts/stackstorm directory at the root of the workroom. This will allow you to edit files using your favorite editor on your computer.

Now, let's setup the contents of the workroom. Create the workroom config file by starting with the example template.

$ cd ~/stackstorm/st2workroom
$ cp hieradata/workroom.yaml.example hieradata/workroom.yaml

Open up the file hieradata/workroom.yaml in your favorite text editor. In here, you will setup the configuration version of StackStorm, and Hubot. In this file, set the following values:

# hieradata/workroom.yaml
---
st2::version: 0.9dev
st2::mistral_git_branch: st2-0.8.1

Next, configure Hubot. Take a look at the commented lines. At the minimum, you must provide:

  • hubot::adapter:
  • hubot::env_export:
    • A list of key/value pairs to inject into Hubot's running environment.
  • hubot::dependencies:
    • This is where you will define which version of Hubot to run, which version of hubot-scripts, and any adapters you need to install.

As an example, here is what configuration looks like for a Hubot Slack

# hieradata/workroom.yaml
---

hubot::adapter: slack
hubot::chat_alias: "!"
hubot::env_export:
  HUBOT_SLACK_TOKEN: "xoxb-XXXX"
  HUBOT_LOG_LEVEL: debug
hubot::git_source: "git@github.com:StackStorm/hubot-stanley.git"
hubot::ssh_privatekey: "XXX"

Pay special attention to the hubot::ssh_privatekey attribute. You will need to supply the private key associated with your GitHub account here. A small helper script is provided to format the SSH key for usage with Hiera. For example, if I wanted to use the SSH key ~/.ssh/id_rsa, I could simply do the following:

$ script/hiera-ssh-privatekey ~/.ssh/id_rsa

Copy and paste the output of this command into the hubot::ssh_privatekey attribute.

After all this is setup, start up the workroom.

$ vagrant up

At any point, you can SSH into this node by navigating to the ~/stackstorm/st2workroom directory, and executing the command vagrant ssh.

This process will take a few minutes, and when completed, a new Hubot should be sitting in your Chat room ready to accept and send commands to StackStorm. Proceed to the section Configure Stackstorm to continue.

Manual Installation

To get started, you will need:

  • StackStorm v0.9dev
  • Hubot
  • StackStorm Hubot adapter

First, start by updating your version of StackStorm. This is typically done by re-running st2_deploy.sh with the updated version code.

$ st2_deploy.sh 0.9dev

Currently, this feature requires st2auth to be disabled. This will be fixed before production release. In the meantime, ensure st2auth is disabled by doing the following:

  • Edit /etc/st2/st2.conf
  • Under the [auth] section, look for the value enable.
  • Make sure the value enable is set to False.
  • Restart StackStorm with st2ctl restart

Now, take a moment to also install and configure Hubot. Instructions on how to configure and deploy Hubot for your platform can be found here. Also ensure it is configured to connect to your chat service of choice. You can find documentation for this at https://github.com/github/hubot/blob/master/docs/adapters.md.

Finally, head to download the st2bot.js adapter for Hubot. For this, you will require access to a private repository where you can download the code. Inside of your Hubot installation, copy the st2bot.js script to the scripts directory of the top level of your bot.

If you are installing Hubot on a machine that is not the same as your StackStorm installation, you will need to set the following environment variables:

  • ST2_API - FQDN + port to StackStorm endpoint. Typically: http://<host>:9101

Once done, start up your Hubot instance. Validate that things are working alright and Hubot is connecting to your client by issuing a default command. For example, if you named your Hubot instance frybot, you can issue the command:

  frybot: the rules

And should get something like this back:

slack

Now, install the hubot pack into your StackStorm installation.

  $ st2 packs.install packs=hubot http://github.com/StackStorm/st2incubator.git

If successful, proceed to the section Configure Stackstorm to continue.

Configuring StackStorm

At this point, it is necessary to introduce a few new terms as it relates to how ChatOps messages are processed internally. First, you will need to create a notification rule. This will leverage the new notifications system, and allow us to send messages back to Hubot. Then, you will configure aliases which map commands from Hubot to actions in StackStorm. Finally, you'll configure actions to use the notifications, thus completing the entire chain of events. Let's get started.

First, let's configure our global notification rule. To do this, let's create a new pack in StackStorm called chatops. Navigate to the artifacts/stackstorm directory, and create a new pack directory.

$ cd ~/stackstorm/st2workroom/artifacts/stackstorm/packs
$ mkdir -p chatops/{actions,rules,sensors,aliases}

Now, let's configure an alias and setup an action to be used in ChatOps. For this example, I am going to download a pack from our st2contrib repository, the Google pack. This will provide us with the action google.get_search_results that we will expose via ChatOps. First, SSH into the vagrant machine and install the pack.

$ cd ~/stackstorm/st2workroom
$ vagrant ssh
$ st2 run packs.install packs=google

Now, let's setup an alias. For purpose of this setup aliases are stored in the directory /opt/stackstorm/packs/chatops/aliases on the filesystem. From your host filesystem, you can access them from ~/stackstorm/st2workroom/artifacts/stackstorm/packs/chatops/aliases. We have already created this directory in a previous step.

$ cd ~/stackstorm/st2workroom
$ cd artifacts/stackstorm/packs/chatops/aliases

Create a new file called google.yaml, and add the following contents.

# packs/chatops/aliases/google.yaml
---
name: "google"
action_ref: "google.get_search_results"
formats:
  - "{{query}}"

Now, navigate to the hubot pack rules directory, and view the notify_hubot rule. This is a notification rule that sets up a notification channel.

$ cd ~/stackstorm/st2workroom/artifacts/stackstorm/packs/hubot/rules
$ vi notify_hubot.yaml

That rule, looks as follows:

# packs/hubot/rules/notify_hubot.yaml
---
name: "hubot.notify_hubot"
enabled: true
description: "Notification rule to send messages to Hubot"
trigger:
  pack: "chatops"
  type: "core.st2.generic.notifytrigger"
criteria:
  trigger.channel:
    pattern: "hubot"
    type: "equals"
action:
  ref: hubot.post_message
  parameters:
    channel: "{{trigger.data.source_channel}}"
    user: "{{trigger.data.user}}"
    message: "{{trigger.data.result}}"

This file is also here to serve as an example on how to setup other notification triggers.

Now, once this is all done, register all the new files we created and reload Hubot. Do this with the following commands:

$ cd ~/stackstorm/st2workroom
$ vagrant ssh -- sudo st2ctl reload --register-all
$ vagrant ssh -- sudo st2ctl restart
$ vagrant ssh -- sudo service hubot restart

This will register the aliases we created, and tell Hubot to go and refresh its command list.

You should now be able to go into your chatroom, and execute the command hubot: google awesome, and StackStorm will take care of the rest.

slack

That's it! Now, you should be able to begin converting actions of all kinds to be ChatOps capable. Go ahead and give the system a shot, and do not be afraid to provide feedback on things that you like and things that can make your experience better. As we learn more about ChatOps and add additional features, we will be updating this document, so stay tuned for hints, tips, and additional features coming over the next few weeks.

Happy ChatOps-ing!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment