Puppet Enterprise 2018.1

Upgrade your PE installation as new versions become available.

Upgrade paths

These are the valid upgrade paths for PE.

If you're on version...Upgrade to...Notes
2018.1.zYou're up to date!
2017.3.z2018.1
2017.2.z2018.1
2017.1.z2018.1
2016.5.z2018.1
2016.4.10 or later2018.1
2016.4.9 or earlierlatest 2016.4.z, then 2018.1To upgrade to 2018.1 from 2015.2.z through 2016.4.9, you must first upgrade to the latest 2016.4.z.
2016.2.z
2016.1.z
2015.3.z
2015.2.z
3.8.x latest 2016.4.z, then 2018.1 To upgrade from 3.8.x, you must first migrate to the latest 2016.4.z. This upgrade requires a different process than upgrades from other versions.

Upgrade cautions

These are the major updates to recent PE versions that you should be aware of when upgrading.

Important: Always back up your installation before performing any upgrade.

PostgreSQL upgrade in PE 2017.3

PE 2017.3 and later uses PostgreSQL 9.6.
  • Before upgrading, make sure you have at least 1.1 times the space used by the existing /opt/puppetlabs/server/data/postgresql directory. Plan for a downtime window of a couple of hours if you have a large database, and don't worry if your upgrade process seems to hang while upgrading the database—it's not hung. 

  • After upgrading, verify that your installation is working as expected (log into the console and check for historical reports and custom classification groups), then free disk space by cleaning up these PostgreSQL 9.4 directories:

    • /opt/puppetlabs/server/data/postgresql/9.4
    • /opt/puppetlabs/server/data/postgresql/activity/PG_9.4*
    • /opt/puppetlabs/server/data/postgresql/classifier/PG_9.4*
    • /opt/puppetlabs/server/data/postgresql/orchestrator/PG_9.4*
    • /opt/puppetlabs/server/data/postgresql/puppetdb/PG_9.4*
    • /opt/puppetlabs/server/data/postgresql/rbac/PG_9.4*
    Important: Don't remove any directories that start with PG_9.6.
  • If you use external PostgreSQL, you must take extra steps to upgrade. For details, see Upgrading PostgreSQL.

  • If you're upgrading with high availability enabled, upgrade and then forget the existing replica, and provision and enable a new replica. For details, see Upgrade with high availability enabled.

JRuby 9k upgrade in PE 2018.1

To support Ruby 2.3, PE 2018.1 and later changes the default setting for JRuby 9k to enabled (puppet_enterprise::master::puppetserver::jruby_9k_enabled: true). This default differs from open source Puppet and from previous versions of PE.
  • After upgrading, update any server-side installed gems or custom extensions to be compatible with Ruby 2.3 and JRuby 9k. For example, if you're using the autosign gem workflow, upgrade the gem to 0.1.3 and make sure you're not using yardoc 0.8.x. See SERVER-2161 for details.

  • If you notice issues with JRuby in PE, file a ticket rather than changing the default parameter to avoid issues when this setting is eventually deprecated.

MCollective deprecation in PE 2018.1

PE 2018.1 and later no longer installs MCollective by default. If you have an existing PE installation that relies on MCollective and you upgrade by installing the new version and then moving agents over, you must enable MCollective when installing 2018.1, prior to migrating agents.

Test modules before upgrade

To ensure that your modules will work with the newest version of PE, update and test them with Puppet Development Kit (PDK) before upgrading.

Before you begin

If you are already using PDK, your modules should pass validation and unit tests with your currently installed version of PDK

Update PDK with each new release to ensure compatability with new versions of PE.

  1. Download and install PDK. If you already have PDK installed, this updates PDK to its latest version. For detailed instructions and download links, see the installing instructions.
  2. If you have not previously used PDK with your modules, convert them to a PDK compatible format. This makes changes to your module to enable validation and unit testing with PDK. For important usage details, see the converting modules documentation. 

    For example, from within the module directory, run:

    pdk convert
  3. If your modules are already compatible with PDK, update them to the latest module template. If you converted modules in step 2, you do not need to update the template. To learn more about updating, see the updating module templates documentation.

    For example, from within the module directory, run:

    pdk update
  4. Validate and run unit tests for each module, specifying the version of PE you are upgrading to. When specifying a PE version, be sure to specify at least the year and the release number, such as 2018.1. For information about module validations and testing, see the validating and testing modules documentation.

    For example, from within the module directory, run:

    pdk validate
    pdk test unit
    The pdk test unit command verifies that testing dependencies and directories are present and runs the unit tests that you write. It does not create unit tests for your module.
  5. If your module fails validation or unit tests, make any necessary changes to your code.

After you've verified that your modules work with the new PE version, you can continue with your upgrade.

Upgrade a monolithic installation

To upgrade a monolithic installation, run the text-based PE installer on your master or master of masters, and then upgrade any additional components.

Before you begin

Back up your PE installation.

If you encounter errors during upgrade, you can fix them and run the installer again.

  1. Download the tarball appropriate to your operating system and architecture.
  2. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  3. From the installer directory, run the installer: sudo ./puppet-enterprise-installer
    Note: To specify a different pe.conf file other than the existing file, use the -c flag:
    sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

    With this flag, your previous pe.conf is backed up to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and a new pe.conf is created at /etc/puppetlabs/enterprise/conf.d/pe.conf.

  4. If you have compile masters, upgrade them.
    SSH into each compile master and run:
    /opt/puppetlabs/puppet/bin/curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<PUPPET MASTER FQDN>:8140/packages/current/upgrade.bash | sudo bash
  5. If you have ActiveMQ hubs and spokes, upgrade them.
    SSH into each hub and spoke and run:
    /opt/puppetlabs/puppet/bin/curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<PUPPET MASTER FQDN>:8140/packages/current/upgrade.bash | sudo bash
  6. Upgrade these additional PE infrastructure components.
    • Agents

    • Razor

    • PE client tools — Install the appropriate version of client tools that matches the PE version you upgraded to.

Upgrade with high availability enabled

To upgrade with high availability enabled, you must forget and then re-create your replica. The replica is temporarily unavailable to serve as backup during this process, so you should time your upgrade to minimize risk.

Before you begin

Back up your PE installation.

  1. Upgrade PE.
  2. Forget your existing replica.
  3. Provision a new replica.
  4. Enable the new replica.

Upgrade a split or large environment installation

To upgrade a split or large environment installation, run the text-based installer on each infrastructure node in your environment, and then upgrade any additional components.

Before you begin

Back up your PE installation.

Note: You must upgrade the components in the order specified.

If you encounter errors during upgrade, you can fix them and run the installer again.

Upgrade the master

Upgrading the master is the first step in upgrading a split or large environment installation.

  1. Download the tarball appropriate to your operating system and architecture.
  2. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  3. Stop the agent service: sudo puppet resource service puppet ensure=stopped
  4. From the installer directory, run the installer: sudo ./puppet-enterprise-installer
    Note: To specify a different pe.conf file other than the existing file, use the -c flag:
    sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

    With this flag, your previous pe.conf is backed up to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and a new pe.conf is created at /etc/puppetlabs/enterprise/conf.d/pe.conf.

  5. When upgrade completes, transfer the installer and the pe.conf file located at /etc/puppetlabs/enterprise/conf.d/ to the next server that you're upgrading a component on.

Upgrade PuppetDB

In a split installation, after you upgrade the master, you're ready to upgrade PuppetDB.

  1. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  2. Stop the agent service: sudo puppet resource service puppet ensure=stopped
  3. From the installer directory, run the installer: sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
  4. When upgrade completes, transfer the installer and the pe.conf file located at /etc/puppetlabs/enterprise/conf.d/ to the next server that you're upgrading a component on.

Upgrade the console

In a split installation, after you upgrade the master and PuppetDB, you're ready to upgrade the console.

  1. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  2. Stop the agent service: sudo puppet resource service puppet ensure=stopped
  3. From the installer directory, run the installer: sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

Run Puppet on infrastructure nodes

To complete a split upgrade, run Puppet on all infrastructure nodes in the order that they were upgraded.

  1. Run Puppet on the master node.
  2. Run Puppet on the PuppetDB node.
  3. Run Puppet on the console node.

Upgrade remaining infrastructure nodes

After the main components of your infrastructure are upgraded, you must upgrade any additional infrastructure nodes, such as compile masters, hubs, and spokes.

  1. If you have compile masters, upgrade them.
    SSH into each compile master and run:
    /opt/puppetlabs/puppet/bin/curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<PUPPET MASTER FQDN>:8140/packages/current/upgrade.bash | sudo bash
  2. If you have ActiveMQ hubs and spokes, upgrade them.
    SSH into each hub and spoke and run:
    /opt/puppetlabs/puppet/bin/curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<PUPPET MASTER FQDN>:8140/packages/current/upgrade.bash | sudo bash
  3. Upgrade these additional PE infrastructure components.
    • Agents

    • Razor

    • PE client tools — Install the appropriate version of client tools that matches the PE version you upgraded to.

Upgrading PostgreSQL

If you use the default PE-PostgreSQL database installed alongside PuppetDB, you don't have to take special steps to upgrade PostgreSQL. However, if you have a standalone PE-PostgreSQL instance, or if you use a PostgreSQL instance not managed by PE, you must take extra steps to upgrade PostgreSQL.

You must upgrade a standalone PE-PostgreSQL instance each time you upgrade PE. To upgrade a standalone PE-PostgreSQL instance, simply run the installer on the PE-PostgreSQL node first, then proceed with upgrading the rest of your infrastructure.

You must upgrade a PostgreSQL instance not managed by PE only when there's an upgrade to PostgreSQL in PE, which occurred most recently in 2017.3. To upgrade an unmanaged PostgreSQL instance, use one of these methods:
  • Back up databases, wipe your old PostgreSQL installation, install the latest version of PostgreSQL, and restore the databases. 

  • Back up databases, set up a new node with the latest version of PostgreSQL, restore databases to the new node, and reconfigure PE to point to the new database_host.

  • Run pg_upgrade to get from the older PostgreSQL version to the latest version.

Note:  If you're upgrading a split installation of a PE version earlier than 2016.4.3 with an external PostgreSQL instance, you must upgrade with the --force flag, for example:
/opt/puppetlabs/puppet/bin/puppet infrastructure configure --detailed-exitcodes --modulepath=/opt/puppetlabs/server/data/enterprise/modules --no-noop --upgrade-from=<PREVIOUS PE VERSION> --force
Upgrading this configuration without the force flag causes the upgrade to hang while searching for the external database.

Text mode installer options

When you run the installer in text mode, you can use the -c option to specify the full path to an existing pe.conf file. You can pair these additional options with the -c option.

Option Definition
-D Display debugging information
-q Run in quiet mode. The installation process isn't displayed. If errors occur during the installation, the command quits with an error message.
-y Run automatically using the pe.conf file at /etc/puppetlabs/enterprise/conf.d/. If the file is not present or is invalid, installation or upgrade fails.
-V Display verbose debugging information.
-h Display help information.
force For upgrades only, bypass PostgreSQL migration validation. This option must appear last, after the end-of-options signifier (--), for example sudo ./puppet-enterprise-installer -c pe.conf -- --force

Checking for updates

To see the version of PE you're currently using, run puppet --version on the command line. Check the PE download site to find information about the latest maintenance release.

Note: By default, the master checks for updates whenever the pe-puppetserver service restarts. As part of the check, it passes some basic, anonymous information to Puppet servers. You can optionally disable update checking.
Back to top