Puppet Integration Guide

Puppet provides a standard way of delivering and operating software, no matter where it runs. With the Puppet approach, you define what you want your apps and infrastructure to look like using a common easy-to-read language. From there you can share, test, and enforce the changes you want to make across your datacenter. And at every step of the way, you have the visibility and reporting you need to make decisions and prove compliance.

In PagerDuty

1. Go to the Configuration menu and select Services.

2. On the Services page:

   • If you are creating a new service for your integration, click Add New Service.

   • If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the New Integration button.

     

     

3. Select your app from the Integration Type menu and enter an Integration Name.

   If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.

4. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.

   

5. Copy the Integration Key for your new integration.

   

In Your Puppet Master Node

1. Install the pdsupport-pagerduty module:

   /opt/puppetlabs/bin/puppet module install pdsupport-pagerduty

2. Install the necessary Ruby dependencies:

   /opt/puppetlabs/server/bin/puppetserver gem install puppet

   /opt/puppetlabs/server/bin/puppetserver gem install json

   /opt/puppetlabs/server/bin/puppetserver gem install redphone

3. Manually install the pagerduty.rb script:

   Note: This step is required due to an issue within Puppet. Details on this issue are documented here.

   cp /etc/puppetlabs/code/environments/production/modules/pagerduty/lib/puppet/reports/pagerduty.rb /opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/reports/

4. Add a pagerduty class to your master node’s main manifest:

   class { 'pagerduty': }

5. List pagerduty as a report handler on your master node’s puppet.conf file:

    [master]
   reports = pagerduty

6. Enable pluginsync and reports on your master and client nodes if it is not already:

   Note: As of Puppet 3.0.0 these settings are true by default. This step is only necessary if either of these settings has been set to false.

   You can manually enable the settings in puppet.conf:

    [master]
   report = true
   pluginsync = true
   [agent]
   report = true
   pluginsync = true

   Or you can enable within the pagerduty class in your master node’s manifest:

   class { 'pagerduty':
   pagerduty_puppet_reports    => 'store,http,pagerduty',
   pagerduty_puppet_pluginsync => 'true',
   }

7. Restart the puppetserver service:

   sudo service puppetserver restart

8. Move the pagerduty.yaml.erb template into your master’s confdir and rename the file pagerduty.yaml:

   mv /etc/puppetlabs/code/environments/production/modules/pagerduty/templates/pagerduty.yaml.erb /etc/puppetlabs/puppet/pagerduty.yaml

9. Edit your pagerduty.yaml file and insert the integration key you copied in step 5 above:

   sudo vi /etc/puppetlabs/puppet/pagerduty.yaml

   ---
   :pagerduty_api: 'INSERT_INTEGRATION_KEY_HERE'

10. To test that a failed run will trigger a PagerDuty incident, edit the pagerduty module’s init.pp manifest and uncomment lines 9-13:

    sudo vi /etc/puppetlabs/code/environments/production/modules/pagerduty/manifests/init.pp

    if ! defined(Service[$pagerduty_puppet_service]) {
    service { $pagerduty_puppet_service :
    ensure => running,
    }
    }

11. Then run the Puppet agent on one of your client nodes:

    /opt/puppetlabs/bin/puppet agent --test

FAQ

What versions of Puppet is this integration compatible with?

This integration has been tested with Puppet 3.x and 4.x. For older versions of Puppet, please see this module, which was built for Puppet 2.x.

Can you integrate Puppet with multiple PagerDuty services?

Each Puppet master node can only be integrated with one PagerDuty service. However, if you have multiple Puppet master nodes in your environment, you can integrate each node with a separate service in PagerDuty. Simply update the integration key in your pagerduty.yaml file to point to the service you would like to integrate with that particular node.

Do incidents resolve automatically in PagerDuty if the run succeeds in Puppet?

Yes, the incident in PagerDuty will resolve as soon as the run is successful.

How are failed Puppet runs de-duplicated in PagerDuty incidents?

The Puppet runs are de-duplicated based upon the host that generated the report.

Where can I find logs to troubleshoot issues with this integration?

Puppet logs are located on your master node in the logdir, which can be configured in puppet.conf. The default directory in Puppet 4.x is:

/var/log/puppetlabs/puppetserver