Tuesday, September 19, 2017

Build a Puppet 5 Master on CentOS 7 -- Hella Quickstyle

Want get going with Puppet 5, but you're in some sort of an insane hurry?  Let me walk you through a "hella quickstyle" install of a Puppet 5 master on CentOS 7.  Starting with a completely new, base CentOS 7 system, here's what to do, as root.

Install the Master

I'll be using Puppet Labs' own yum repositories for the install.  The repository definition can be installed by grabbing an RPM.

  rpm -Uvh https://yum.puppetlabs.com/puppet5/puppet5-release-el-7.noarch.rpm

Now it's a piece of cake to install the puppetserver package and its dependencies.

  yum -y install puppetserver

The default configuration has the master's JVM start with a 2 gb heap size.  That's way more than I need.  (Your mileage will vary.)  Let's bring that size down.

  sed -i -e 's/-Xms2g -Xmx2g/-Xms128m -Xmx512m/' /etc/sysconfig/puppetserver

Now I can start up the Puppet server.

  systemctl start puppetserver

If you like, make a symlink to the puppet binary in /usr/local/bin.

  ln -s /opt/puppetlabs/puppet/bin/puppet /usr/local/bin/puppet

The package adds configuration for the master, but not the agent, so I'll add a stanza telling the agent to fetch catalogs from itself.

  cat >> /etc/puppetlabs/puppet/puppet.conf <<EOF
  [agent]
    server = `hostname -f`
  EOF

Now the agent should be able to run.

  puppet agent --test

Finally, I'm going to tell firewalld to allow TCP connections to port 8140, so that other nodes can request catalogs from my master.

  cat > /etc/firewalld/services/puppetmaster.xml <<EOF
  <?xml version="1.0" encoding="utf-8"?>
    <service>
      <short>puppetmaster</short>
      <description>Puppet Master</description>
      <port protocol="tcp" port="8140"/>
    </service>
  EOF

  firewall-cmd --permanent --add-service=puppetmaster   # may take two tries
  firewall-cmd --reload

Add PuppetDB

Next, I'll use Puppet to install and configure PuppetDB.  First, I need to install a module.  I'm not going to use r10k to manage the modules I need, but in the real world, you probably would.  I'm just going to use the Puppet Module Tool to throw it directly into the production code environment.

  puppet module install puppetlabs-puppetdb

Now I classify my master with puppetdb classes.  I'm going to add a node definition for my master to the site.pp manifest.  (And I'll add a default node, for the future.)  When I declare the puppetdb class, I'll tune my memory requirements down, and tell it not to manage my firewall.

  cat >> /etc/puppetlabs/code/environments/production/manifests/site.pp <<EOF
  node '`hostname -f`' {
    # Install and configure PuppetDB
    class { 'puppetdb':
      java_args => { '-Xms' => '128m', '-Xmx' => '256m' },
      manage_firewall => false,
    }
    # And configure the master to use PuppetDB
    include puppetdb::master::config
  }

  node default {
    notify { 'Default node definition ... no classification found!':}
  }
  EOF

Let's make sure it's working.  First, do an agent run, which should make the master submit a report to the PuppetDB.

  puppet agent --test

And now try a (convoluted) curl request straight into the local PuppetDB, to list nodes that are classified with the "Puppetdb" class.  Note: if you adapt and re-use this later, make sure to run it from the master.

  curl -X GET \
    --tlsv1 \
    --stderr /dev/null \
    --data-urlencode "query=[\"and\",[\"=\",\"type\",\"Class\"],[\"=\",\"title\",\"Puppetdb\"]]" \
    --cert   $(puppet config print hostcert) \
    --key    $(puppet config print hostprivkey) \
    --cacert $(puppet config print localcacert) \
    https://`hostname f`:8081/pdb/query/v4/resources | python -m json.tool

Add Agent Nodes

For quick reference, here are the steps to add just the Puppet agent to a node.  All you need to do is add a yum repo, install the puppet-agent package, aim it at your new master, and run.  Make sure  to replace FQDN_OF_YOUR_MASTER in the example below.

  rpm -Uvh https://yum.puppetlabs.com/puppet5/puppet5-release-el-7.noarch.rpm
  yum -y install puppet-agent
  cat >> /etc/puppetlabs/puppet/puppet.conf <<EOF
  [agent]
    server = FQDN_OF_YOUR_MASTER
  EOF
  puppet agent --test --waitforcert 10

Future Direction

These instructions use the Puppet module tool to install the puppetdb module.  That throws it directly into /etc/puppetlabs/code/environments/production/modules.  Most production-grade Puppet masters use 'r10k' to manage the modules that they need, automatically pulling them from version control or the forge, rather than adding them by hand.  The documentation for r10k is here.