Upgrading from Puppet 4 to 5

This wiki page was written at the release of Foreman 1.16 and should be used at your own risk.

This wiki page is a rough guide on how to upgrade from Puppet 4 to Puppet 5 when using Foreman. It doesn't replace Puppet's own documentation - you need to take both into account, and it's not for the faint-hearted.

Remember, Puppet is a separate piece of software to Foreman. Foreman integrates with Puppet in only a few places (e.g. reports, ENC and smart proxy class imports) but the Foreman installer may have set it up for you initially.

If you're unfamiliar with how Puppet works, then you should consider setting up a new installation and migrating hosts instead.

Planning

Ensure you are running Foreman 1.16 or higher, previous versions are not compatible with Puppet 5. See Upgrading to Foreman 1.16 for more information.

  • As with any upgrade, the smaller the step, the easier it will be. Ensure you've already upgraded to the latest 4.x release and fixed any deprecations from the release notes before moving to 5. This will save time later.
  • Ensure your Puppet modules are going to be compatible with Puppet 5
  • If you're using PuppetDB, you need to upgrade its PostgreSQL database to 9.6.
  • Plan to upgrade your masters before your agents, because the master can serve older agents, but not the other way around.
  • Back up everything, especially SSL keys and certificates.

Doing

Make sure, everything is foreman-installer managed.

This means, if you're running foreman-installer -n, no changes should be visible in /var/log/foreman-installer/foreman.log. Otherwise, change your installer configuration to match your desired configuration.

Change Repositories

Configure the new Puppet 5 repositories with the Using Puppet 5 Platform instructions.

Optionally, remove the respective PC1 package (puppetlabs-release-pc1 or similar).

Upgrade Puppet Packages.

Run yum update or apt-get dist-upgrade. If you want to upgrade only Puppet packages, pull these out from the list of package to get updated from these commands.

Be sure to replace /etc/puppetlabs/puppetserver/conf.d/web-routes.conf with the version that's coming with the Puppetserver 5 package.

Prepare And Run The Installer

Reinstall the puppet-agent-oauth package, by running yum reinstall puppet-agent-oauth or apt-get install --reinstall puppet-agent-oauth.

Run the installer, resetting parameters, which changed for Puppetserver 5:
foreman-installer --reset-puppet-server-jvm-extra-args --reset-puppet-server-puppetserver-version --reset-puppet-server-puppetserver-metrics --reset-puppet-server-puppetserver-experimental

Done

You should be good.