Migrating the Puppet Master Config

This is very straightforward. Copy the entire block named [master] from /etc/puppet/puppet.conf on an existing Puppet master. Add this to /etc/puppetlabs/puppet/puppet.conf on the new Puppet server you have created.

After you have done that, you’ll need to perform the following changes:

Check the previous master’s puppet.conf for settings in [main]

Check the master’s [main] section for any variables that affect the server configuration. Refer to “Configuring Puppet Server” if necessary. Some master settings could be placed in the wrong section of the config. If in doubt, copy the entire section.

Remove file paths found in the file

As every directory has changed with the migration to Puppet 4, it is best to comment out or remove every path you find in the configuration file. Embrace the new, more consistent path structure.

(Testing) Adjust the certname parameter in the [master] block

If you are building a separate and distinct server intended only to test your modules for compatibility with Puppet 4, adjust the certname parameter to indicate the new server name. If you are building a drop-in replacement for the previous Puppet master, leave the name the same.

(Production) Copy the entire TLS file hierarchy

If you are creating a drop-in replacement for an existing Puppet master, copy the entire file hierarchy to the new /var/opt/puppetlabs/puppetserver/ssl/ directory:

$ sudo rsync -aHv oldmaster:/var/lib/puppet/ssl 
      /var/opt/puppetlabs/puppetserver/

Synchronizing All Environments

Sync the entire environment directory structure from the previous Puppet master to the new server. If you were already using environments, this could be as simple as the following command (adjust the server names and the source path as necessary):

$ rsync -aHP oldmaster:/etc/puppet/environments /etc/puppetlabs/code/

If you were not using environments previously, then I recommend the following approach:

$ cd /etc/puppetlabs/code
$ rsync -aHP oldmaster:/etc/puppet/modules environments/production/

You could also copy the modules into basemodulepath or /etc/puppetlabs/code/modules. This directory is sourced as a backup for modules shared across all environments. It is simpler, but it has limitations (which we’ll discuss in Part IV).

$ rsync -aHP oldmaster:/etc/puppet/modules /etc/puppetlabs/code/

After you have copied these files, you’ll need to update any files that have Puppet config paths to reflect Puppet 4 standards. These are most likely to be environment configuration files: /etc/puppetlabs/code/environments/*/environments.conf, but if you have a Puppet module that configures Puppet for your nodes (like the puppet module created in Chapter 13), then you’ll need to update the paths in that as well.

I have found the following commands very helpful for finding paths that may need to be updated (you may want to check other paths depending on your old Puppet file paths):

$ grep -rH etc/puppet /etc/puppet /etc/puppetlabs
$ grep -rH var/lib/puppet /etc/puppet /etc/puppetlabs

Copying Hiera Data

Copy the Hiera configuration file from the previous master to the new Puppet server. This is usually installed in /etc/puppet/hiera.yaml on previous Puppet versions. You’ll want to copy this file to /etc/puppetlabs/puppet/hiera.yaml:

$ scp -aHv oldmaster:/etc/puppet/hiera.yaml /etc/puppetlabs/code/
$ rsync -aHP oldmaster:/etc/puppet/hieradata /etc/puppetlabs/code/

After you have copied the file, you’ll need to update the paths in the file to reflect Puppet 4 standards. If you were not using environments before, your Hiera configuration file may have had paths like this:

:yaml:
  :datadir: /etc/puppet/hieradata

If you want all environments to share the same Hiera data like the preceding example, you can adjust it as follows:

:yaml:
  :datadir: /etc/puppetlabs/code/hieradata

If you had separate copies of data for each environment, it may have had paths that utilized the environment variable in the path:

:yaml:
  :datadir: /etc/puppet/environments/%{::environment}/hieradata

Adjust it to use the $environmentpath standard for Puppet 4 utilizing the $::environment variable:

:yaml:
  :datadir: /etc/puppetlabs/code/environments/%{::environment}/hieradata

Ensure that you utilize the :: top-level prefix on this variable.

Finally, copy over the Hiera data to the location referenced in the configuration you just adjusted:

$ rsync -aHP oldmaster:/etc/puppet/hieradata /etc/puppetlabs/code/

Or:

$ cd /etc/puppetlabs/code
$ rsync -aHP oldmaster:/etc/puppet/hieradata environments/production/

This should work suitably for testing, as Hiera is backward-compatible. You’ll want to upgrade the Hiera configuration format to version 5, and move environment data into the per-environment Hiera configuration discussed in Chapter 11.

Moving the MCollective Config Directory

If you were using MCollective previously, copy its configuration files from the previous Puppet master to the new server. These were installed in /etc/mcollective previously. Copy the entire hierarchy to /etc/puppetlabs/mcollective/:

$ sudo rsync -aHv oldmaster:/etc/mcollective /etc/puppetlabs/

After you have copied the files, you will need to update paths in the configuration files to reflect the new Puppet file paths. Adjust any paths that reference /etc/mcollective with /etc/puppetlabs/mcollective.

Add the following line to both the server.cfg and client.cfg files:

libdir = /opt/puppetlabs/mcollective/plugins

This adds the new AIO installer paths to the library load path. Leave the old libdir lines in the file as many plugins still install in the OS standard directories.

Removing Node Inheritance

If you were using node inheritance to apply common classes to groups of systems in manifests/site.pp/ or another file imported there, you’ll need to break this up into Hiera class assignments. Node assignment remains possible in Puppet 4, but node inheritance has been completely removed.

For example, this assignment style:

node 'puppetserver' inherits default {
  class { 'puppet::server': }
}
node 'webserver' inherits default {
  class { 'apache': }
}
node default {
  class { 'ntp': }
  class { 'puppet::agent': }
}

will yield this result:

ERROR [puppet-server] Puppet Node inheritance is not supported in Puppet >= 4.0.0
See http://links.puppetlabs.com/puppet-node-inheritance-deprecation

The ability to look up classes in Hiera data has significantly improved this situation. You can now assign classes to nodes based on Hiera’s flexible hierarchy of information sources.

The alternative is much cleaner and easier to read when many systems are involved. Start by adding the following lookup to the manifests/site.pp, which does nothing more than look up classes to declare from Hiera and other data sources:

# Lookup all classes defined in Hiera and other data sources
lookup('classes', Array[String], 'unique').include

Then create a default YAML definition for classes in hieradata/common.yaml with the list of classes that every node applies:

classes:
  - ntp
  - puppet::agent

Finally, remove every inherits from the node definitions in the manifest. This won’t get you all the way to proper Hiera-assigned classes as described in “Assigning Modules to Nodes”, but it will get you past the loss of node inheritance in Puppet 4.

Take the time and make the investment in using the Hiera hierarchy for class assignment. It may seem like a difficult change, but once you’ve gained the advantages you’ll be pleased with the outcome.

Testing a Client Node

At this time, you can now test your manifests, exactly as you would with an older Puppet master:

[vagrant@client ~]$ sudo puppet agent --test --server=puppet.example.com
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Loading facts
Info: Caching catalog for client.example.com
Info: Applying configuration version '1438557124'

It is hard to predict what you will see at this point, as it depends on how your modules and data are configured. If your modules were written according to Puppet 3 best practices, you may have very little that is necessary to fix. Many of my own modules worked with zero or just a few changes with Puppet 4.

Don’t assume that no visible errors means no problems were found. Check the client logfile (/var/log/messages) and the server logfile (/var/log/puppetlabs/puppetserver/puppetserver.log) for warnings and deprecation messages.

If you see any problems in the client or server logfiles, go through the modules and adjust them to work properly in a Puppet 4 environment. You may want to refer back to these parts of the book for information specific to upgrades:

• “Reviewing Puppet 4 Changes”
• Chapter 8

Upgrading Clients

Puppet Server contains backward-compatible functions to support Puppet 3 clients, albeit with some limitations. In contrast, the Puppet 4 master will not support Puppet 3 clients. Try connecting one when running it in foreground mode, and you’ll get a clear warning about this:

[vagrant@puppetmaster ~]$ sudo puppet master --verbose --no-daemonize
Info: Not Found: Error: Invalid URL - 
  Puppet expects requests that conform to the /puppet and /puppet-ca APIs.

Note that Puppet 3 agents aren't compatible with this version;
 if you're running Puppet 3, you must either upgrade your agents to match the
 server or point them to a server running Puppet 3.

There are two ways to handle this:

• Put an upgrade module on the Puppet 3 master that installs Puppet 4 on client nodes.
• Replace the Puppet 3 master with Puppet Server.

No matter which option you choose, you’ll need a module that removes the old Puppet configuration and replaces it with Puppet 4. You learned how to build one in Part II.