Puppet Master and Puppet Server

The terminology around the master software might be a little confusing. That's because both the terms, Puppet Master and Puppet Server, are floating around, and they are closely related too. Let's consider some technological background in order to give you a better understanding of what is what.

Puppet's master service mainly comprises a RESTful HTTP API. Agents initiate the HTTPS transactions, with both sides identifying each other using trusted SSL certificates. During the time when Puppet 3 and older versions were current, the HTTPS layer was typically handled by Apache. Puppet's Ruby core was invoked through the Passenger module. This approach offered good stability and scalability.

Puppet Labs has improved upon this standard solution with a specialized software called puppetserver. The Ruby-based core of the master remains basically unchanged, although it now runs on JRuby instead of Ruby's own MRI. The HTTPS layer is run by Jetty, sharing the same Java Virtual Machine with the master.

By cutting out some middlemen, puppetserver is faster and more scalable than a Passenger solution. It is also significantly easier to set up. Towards the end of this chapter, the two approaches are recapped and visually compared.

Setting up the master machine

Getting the puppetserver software onto a Linux machine is just as simple as the agent package (which you did at the very beginning of Chapter 1, Writing Your First Manifests). At the time of writing this, distribution packages were available on Red Hat Enterprise Linux and its derivatives. For Debian and Ubuntu, it was still necessary to rely on Puppet Labs' own repositories to get the software.

A great way to get Puppet Labs packages on any platform is the Puppet Collection. Shortly after the release of Puppet 4, Puppet Labs created this new way of supplying software. This can be considered as a distribution in its own right. Unlike Linux distributions, it does not contain a Kernel, system tools, and libraries. Instead, it comprises various software from the Puppet ecosystem. Software versions that are available from the same Puppet Collection are guaranteed to work well together.

Use the following commands to install puppetserver from the first Puppet Collection (PC1) on a Debian 7 machine. (The Collection for Debian 8 has not yet received a puppetserver package at the time of writing this.)

root@puppetmaster# wget http://apt.puppetlabs.com/puppetlabs-release-pc1-wheezy.deb
root@puppetmaster# dpkg -i puppetlabs-release-pc1-wheezy.deb
root@puppetmaster# apt-get update
root@puppetmaster# apt-get install puppetserver

The puppetserver package comprises only the Jetty server and the Clojure API, but the all-in-one puppet-agent package is pulled in as a dependency.

Specifically, you can use the puppet command on the master node. You will soon learn how this is useful. However, when using the packages from Puppet Labs, everything gets installed under /opt/puppetlabs. It is advisable to make sure that your PATH variable always includes the /opt/puppetlabs/bin directory so that the puppet command is found here.

Regardless of this, once the puppetserver package is installed, you can start the master service:

root@puppetmaster# service puppetserver start

Depending on the power of your machine, the startup can take a few minutes. Once initialization completes, the server will operate very smoothly though. As soon as the master port 8140 is open, your Puppet master is ready to serve requests.

puppet master –-no-daemonize

Creating the master manifest

When you used Puppet locally in Chapter 1, Writing Your First Manifests, you specified a manifest file that puppet apply should compile. The master compiles manifests for many machines, but the agent does not get to choose which source file is to be used—this is completely at the master's discretion. The starting point for any compilation by the master is always the site manifest, which can be found in /opt/puppetlabs/code/environments/production/manifests/.

Each connecting agent will use all the manifests found here. Of course, you don't want to manage only one identical set of resources on all your machines. To define a piece of manifest exclusively for a specific agent, put it in a node block. This block's contents will only be considered when the calling agent has a matching common name in its SSL certificate. You can dedicate a piece of the manifest to a machine with the name of agent, for example:

node 'agent' {
  $packages = [ 'apache2', 
    'libapache2-mod-php5', 
    'libapache2-mod-passenger', ] 
  package { $packages:
    ensure => 'installed', 
    before => Service['apache2'], 
  } 
  service { 'apache2': 
    ensure => 'running', 
    enable => true, 
  }
}

Before you set up and connect your first agent to the master, step back and think about how the master should be addressed. By default, agents will try to resolve the unqualified puppet hostname in order to get the master's address. If you have a default domain that is being searched by your machines, you can use this as a default and add a record for puppet as a subdomain (such as puppet.example.net). Otherwise, pick a domain name that seems fitting to you, such as master.example.net or adm01.example.net. What's important is the following:

The mode of resolution depends on your circumstances—the hosts file on each machine is one ubiquitous possibility. The Puppet server listens on all the available addresses by default.

This leaves the task of creating a suitable certificate, which is simple. Configure the master to use the appropriate certificate name and restart the service. If the certificate does not exist yet, Puppet will take the necessary steps to create it. Put the following setting into your /etc/puppetlabs/puppet/puppet.conf file on the master machine:

[master]
certname=master.example.net

Upon its next start, the master will use the appropriate certificate for all SSL connections. The automatic proliferation of SSL data is not dangerous even in an existing setup, except for the certification authority. If the master were to generate a new CA certificate at any point in time, it would break the trust of all existing agents.

Inspecting the configuration settings

All the customization of the master's parameters can be made in the puppet.conf file. The operating system packages ship with some settings that are deemed sensible by the respective maintainers. Apart from these explicit settings, Puppet relies on defaults that are either built-in or derived from the environment (details on how this works follow in the next chapter):

root@puppetmaster # puppet master --configprint manifest
/etc/puppetlabs/code/environments/production/manifests

Most users will want to rely on these defaults for as many settings as possible. This is possible without any drawbacks because Puppet makes all settings fully transparent using the --configprint parameter. For example, you can find out where the master manifest files are located.

To get an overview of all available settings and their values, use the following command:

root@puppetmaster# puppet master --configprint all | less

While this command is especially useful on the master side, the same introspection is available for puppet apply and puppet agent.