Puppet 3.x to 4.x agent upgrades

This version is out of date. For current versions, see Puppet packages and versions.

Although there are a lot of changes to Puppet agent configuration in Puppet 4, the process of upgrading agents can be automated in a way that server upgrades can’t.

Decide how to upgrade your nodes

We provide a module called puppet_agent to simplify upgrades from Puppet 3 to 4.

If you’re running Puppet on Windows or any supported Linux operating system, this module can automatically upgrade Puppet, MCollective, and all of their dependencies on agents.

If you’re running Puppet on other operating systems, you can’t upgrade them with the module. You can either upgrade your agents manually or automate the process yourself.

The next steps explain both methods.

Upgrade with the puppet_agent module

Note: This module works on Windows and supported Linux distributions. If your agents run any other operating systems, skip to “Upgrade Manually or Build Your Own Automation”.

The puppet_agent module does the following things for you:

  • Enables the Puppet Collection 1 (PC1) repository, if applicable.
  • Installs the latest version of the puppet-agent package, which replaces the installed versions of Puppet, Facter, Hiera, and MCollective.
  • Copies Puppet’s SSL files to their new location.
  • Copies your old puppet.conf to Puppet 4’s new location, and cleans out old settings that we either removed in Puppet 4 or needed to revert to their default values.
  • Copies your MCollective server and client configuration files to their new locations, and adds the new plugin path to the libdir setting.
  • Ensures the Puppet and MCollective services are running.

The puppet_agent module is completely inert on nodes already running Puppet 4—its only purpose is to help you upgrade from Puppet 3.

  1. Install the module on Puppet servers.

    • If you manage your Puppet code manually, install it by running puppet module install puppetlabs/puppet_agent --environment <ENVIRONMENT>
    • If you manage your code with r10k, add the module and its dependencies to your Puppetfile.
    • If you manage your code some other way, install puppet_agent as you would any other module.
  2. Assign the puppet_agent class to nodes.

    However you classify nodes — whether in the main mainfest, with an external node classifier or Hiera, or some other method — classify your agents with puppet_agent.

    You can also configure the module to control which services start or to force a different architecture on Windows.

    Carefully control and monitor the rollout. Assign the class in a development or test environment to ensure it works as expected on systems similar to your production environment. Roll it out to your live agents in phases, and monitor the upgraded agents for issues.

  3. Post-upgrade clean-up

    After you’ve upgraded your entire deployment, do the post-upgrade clean-up tasks.

Upgrade manually or build your own automation

To upgrade agents without using the puppet_agent module, you can either install the upgrades manually or design your own upgrade automation.

  1. Install the new version of Puppet.

Find your operating system in the sidebar navigation to the left and follow the Puppet agent installation instructions.

  1. Move SSL files (*nix only).

    On *nix systems, we moved the default confdir to /etc/puppetlabs/puppet in Puppet 4. Since the default ssldir is $confdir/ssl, its location changes during the upgrade.

    In Puppet 3, the default ssldir is /etc/puppet/ssl; some systems might also use /var/lib/puppet/ssl.

    Locate your ssldir in /etc/puppet/puppet.conf and move that directory’s contents to /etc/puppetlabs/puppet/ssl without changing the files’ permissions. For example, run sudo cp -rp /var/lib/puppet/ssl /etc/puppetlabs/puppet/ssl.

  2. Reconcile puppet.conf.

    On *nix systems, we moved puppet.conf from /etc/puppet/puppet.conf to /etc/puppetlabs/puppet/puppet.conf. Either edit the new puppet.conf file or copy your old version. (We didn’t change puppet.conf’s location on Windows.)

    Examine the new puppet.conf regardless of your operating system and confirm that:

  3. Start service or update cron job.

    We also moved Puppet binaries to /opt/puppetlabs/bin in Puppet 4. If you run Puppet as a service, configure it to launch at boot using /opt/puppetlabs/bin/puppet resource:

    /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

    On Windows, use the same command but omit the /opt/puppetlabs/bin/ prefix.

    If you use a cron job to periodically run puppet agent -t on your *nix systems, edit the job and update the puppet binary’s path to /opt/puppetlabs/bin/puppet.

  4. Reconcile MCollective configuration files (*nix only)

    On *nix systems, we moved MCollective’s configuration files from /etc/mcollective to /etc/puppetlabs/mcollective.

    Edit the new configuration files to port over any settings you need from the old configuration files. The default plugin and library directories also changed; update your settings to use the new directories and any other directories you wish to use.

  5. After you’ve upgraded your entire deployment, do the post-upgrade clean-up tasks.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.