Deploying Puppet Open Source

Update: (5/28/17) yes, there is the puppet/r10k which supercedes the zack/r10k. While you are free to deviate from the article in your own environment, the below steps still work as intended. I will have to update this article as well as explain why having r10k and dynamic environments is a good idea.

In this guide we will go over best practices to deploy Puppet Open Source using the recommended workflow (r10k), PuppetDB, and the foreman. You can deploy Puppet server on any of their supported *nix distributions. In this tutorial we will assume it to be on CentOS 7 as this seems to have the best support.

The overall scope of this tutorial is as follows:

1. Set up foreman
2. Set up a control repo
3. Download r10k module
4. Run puppet apply on r10k.pp (with web hook)
5. Set up PuppetDB

Foreman installation is the easiest. Just head over to https://www.theforeman.org/manuals/1.12/index.html#2.1Installation, select CentOS 7 and follow the 5 easy steps. The defaults are fine, but if you want to provision hosts on Digital Ocean or Amazon Web Services, be sure to use interactive mode (the -i switch on foreman-installer) and configure those settings. You can also re-run the installer as it will remember previous settings. Since the foreman installer is built with puppet, it will not override any settings – just enforce them. This allows running the foreman-installer on an already provisioned puppetserver non-destructive.

The control repo is the next step and is also very easy to perform. Just fork the Puppet control-repo to a local git repository or private git location. Instructions are included in the repo on how to set it up on a gitlab server.

Once foreman has installed completely, install the zack/r10k module to manage r10k by running puppet module install zack-r10k. This downloads all prerequisites for managing r10k and getting the ball rolling on a great DevOps practice. You will then need to apply a new puppet manifest to manage r10k’s installation and configuration. You can do that by creating r10k-install.pp with the following contents:

#Fixes Puppet 4 path for webhook
file {'/usr/local/bin/puppet':
  ensure => link,
  target => '/opt/puppetlabs/bin/puppet',
}

class { 'r10k':
  # Point this to your forked control-repo
  remote       => 'git@localgitrepo:puppet/control-repo.git',
  # You will need to create this ssh-key pair
  git_settings => {
     'private_key' => '/etc/puppetlabs/puppetserver/r10k',
  }
}

# Instead of running via mco, run r10k directly
class {'r10k::webhook::config':
  use_mcollective  => false,
  # replace the file names with the correct cert names
  public_key_path  => '/etc/puppetlabs/puppet/ssl/certs/puppet.example.org.pem',
  private_key_path => '/etc/puppetlabs/puppet/ssl/private_keys/puppet.example.org.pem',
}

# this exposes https://0.0.0.0:8088/payload for git webhooks
class {'r10k::webhook':
  use_mcollective => false,
  user            => 'root',
  group           => '0',
  require         => Class['r10k::webhook::config'],
}

With that file saved, run puppet apply r10k.pp. This will enforce and set up r10k.

One of the last things I do on a new Puppet 4 installation is set up PuppetDB. PuppetDB is used to collect exported resources and return them to nodes that want them (i.e. the built-in nagios plugin). By now you should already have puppet installed and working without error. To add PuppetDB into the environment, it is as simple as editing the Puppetfile in your control repo to have mod 'puppetlabs/puppetdb' and matching the dependencies for the PuppetDB module. Next edit your site.pp manifest to include the following:

node 'puppet' {
  # Configure puppetdb and its underlying database
  class { 'puppetdb': }
  # Configure the Puppet master to use puppetdb
  class { 'puppetdb::master::config': }

  # ... r10k stuff should go here. Make sure to add the module and its dependencies to the Puppetfile!
}

On the next puppet run, you should have a solid Puppet environment. Your next step would be to set up the git webhook. This is so that every time you push changes to the repo, r10k updates them on your puppet master. Welcome to the club 🙂