Puppet Enterprise for HipChat add-on

Table of Contents

1. Module Description
2. Setup
3. Usage
4. Limitations - OS and Puppet compatibility

Module Description

This module installs the Puppet Enterprise for HipChat add-on that communicates with your Puppet Enterprise infrastructure.

The Puppet Enterprise for HipChat add-on enables continuous awareness of the status of Puppet jobs and infrastructure change. The add-on enables infrastructure change to be pushed directly from HipChat, change to be monitored discussed as a team as it occurs, and direct control of change as it's occuring.

Setup

Requirements

• Puppet Enterprise 2015.3+
• Puppet Enterprise orchestration service enabled
• Puppet Enterpries file sync service enabled
• A valid signed certificate (not self signed and does not require custom CA certificate). See Plan SSL implemtnation
• A postgresql server (Can be installed on the same host as the Puppet Enterprise for HipChat add-on)
• The following modules in your Puppetfile:
  • puppetlabs/ruby
  • puppetlabs/firewall
  • puppetlabs/gcc
  • puppetlabs/stdlib
  • puppetlabs/concat

Generate access tokens

The Puppet Enterprise for HipChat add-on continuously scans the Puppet Enterprise orchestration service for new and changed Puppet jobs. To do this, the add-on needs an access token to authenticate with the orchestration service.

1. Create a Puppet Enterprise RBAC user for the add-on. Name the user whatever you like, but we recommend something obvious like pe-hipchat-addon. Note the add-on itself will never create Puppet jobs so the access token will be treated as a read-only token. We use a user's access token to create, access, and control Puppet jobs.
2. Create an access token. From the command line of a system with the PE client tools installed, run the command puppet access login --service-url https://$(puppet config print server):4433/rbac-api --lifetime 1y --print. Note, this sets the token to expire in a year. Set the lifetime to whatever value is appropriate. Log in with the user credentials you created in the previous step.
3. Save the credentials. Grab the token that was printed to the screen and hang on to it for later.

Plan SSL implementation

The Puppet Enterprise for HipChat add-on service serves on port 8080. However, HipChat requires all add-ons serve over SSL with valid non-self-signed certificates. You have two options:

Option 1: Use an existing SSL proxy

If you already have an SSL proxy in place, you can configure the proxy to direct add-on traffic to the add-on app. If you choose this route, be sure to configure the puppet_hipchat_url parameter for the puppet_hipchat application declaration.

Option 2: Put an SSL proxy on the Puppet Enterprise for HipChat add-on host

This module includes an example SSL proxy application called puppet_hipchat::ssl that will create an nginx proxy that manages the SSL termination. See Add the optional SSL app for more information

Usage

Add the puppet_hipchat app

In your site.pp, declare an instance of the puppet_hipchat application in your site { } stanza. If you don't have a site stanza, create it.

For example:

site {
  puppet_hipchat { 'production':
    dbuser               => 'hipchat',
    dbpass               => 'hipchat',
    listen_address       => '0.0.0.0',
    hipchat_user_token   => lookup('hipchat_user_token'),
    nodes                => {
      Node['postgresql.example.com'] => [
        Puppet_hipchat::Db['production'],
      ],
      Node['hipchat-addon.example.com'] => [
        Puppet_hipchat::App['production'],
      ]
    }
  }
}

Specify the Puppet Enterprise for HipChat add-on's Puppet Enterprise access token you generated during the Setup for the hipchat_user_token parameter or put in Hiera and use the lookup function like in the example above.

Replace the postgresql.example.com and hipchat-addon.example.com with the hosts where your Postgresql server and Puppet Enteprise for HipChat add-on host are, respectively. Note, they can be the same host. We recommend using the puppetlabs/postgresql module for managing Postgresql servers. Below is an example classification that will work well in a profile:

  class { 'postgresql::server':
    ip_mask_allow_all_users => '0.0.0.0/0',
    listen_addresses        => '*',
  }

  class { 'postgresql::lib::devel': }

Add the optional SSL app

If you'd like to terminate SSL on the same host as the Puppet Enterprise for HipChat add-on host, there is an example puppet_hipchat::ssl application in this module you can use to set up a NGINX SSL terminated proxy.

It takes two parameters: ssl_cert and ssl_key that are absolute paths to where it can find the SSL cert and key. You will need to manage the cert and key on the host using whatever mechanism you use, such as hiera eyaml, to manage sensitive host information.

For example:

  puppet_hipchat::ssl { 'production':
    ssl_cert => '/etc/pki/tls/certs/example.domain.pem',
    ssl_key  => '/etc/pki/tls/private/example.domain.pem',
    nodes    => {
      Node['hipchat-addon.example.com'] => [
        Puppet_hipchat::Ssl_proxy['production'],
      ]
    },
  }

Deploy the app

From the command line of a system with the PE client tools installed, run the command puppet job run puppet_hipchat --service-url https://`puppet config print server` --environment "<production/qa/dev/etc>"

The puppet job run command will deploy the Puppet Enterprise for HipChat add-on application, including the necessary databases in the enviornment you specified. Note the puppet_hipchat application and site stanza declaration will have to be in the environment you want to deploy to.

Limitations and support

This is a tech preview and has known user interface bugs. It has been tested against Puppet Enterprise 2016.1 and CentOS 7 only.

Release 1.0.0

Summary

First Release. See README for description.