Upgrading Puppet Enterprise: Monolithic

You can upgrade your monolithic PE infrastructure as new releases become available.

Supported upgrade paths

We support the following upgrade paths. Note that the 2016.4 line is our long-term support release line.

PE version Upgrade from
2017.2.2 Any .z release from the following versions:
  • 2017.1.z
  • 2016.5.z
  • 2016.4.z
  • 2016.2.z
  • 2016.1.z
  • 2015.3.z
  • 2015.2.z

On PE 3.8?

If you are on PE 3.8, follow the 3.8 to 2017.2 migration documentation, as upgrades from 3.8 are not supported. In addition, the Puppet 3 to Puppet 4 upgrade guide contains useful information about about preparing your Puppet code for migrating from PE 3.8.x to later versions.

Upgrade a monolithic installation

When you upgrade a monolithic installation, the main components of PE (the Puppet master, PuppetDB, and the PE console) are upgraded on the same node.

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

Before you begin: If your master is set to noop mode (noop = true in puppet.conf on the master), remove or comment out this flag prior to upgrade. The installer fails if you attempt to upgrade in noop mode.

  1. Download and unpack the PE installation tarball: tar -xf <tarball>

    You need about 1 GB of space to untar the installer.

  2. From the installer directory, run the installer. The steps vary depending on the path you choose.

    • To use a pe.conf file that already exists, run the upgrade with the -c flag pointed at the pe.conf file.

      sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
      

      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.

      Warning: If you’re using a pre-populated file, be sure you’ve set the parameters correctly as detailed in the following steps.

    • To have the installer open a copy of pe.conf for you to edit and upgrade with, run the installer without the -c flag.

      sudo ./puppet-enterprise-installer
      
  3. Set the console admin password in pe.conf.

    Parameter Value
    "console_admin_password": "<PASSWORD>" Replace <PASSWORD> with your password used to log into the PE console.

    Tip: On a monolithic upgrade, you can leave the default value of "%{::trusted.certname}" if the certname of your monolithic server matches its FQDN.

  4. If you use external PostgreSQL, set required parameters in pe.conf.

    Important: Don’t use single quotes on parameter values. Use double quotes as shown in the examples. Substitute the database user names if you’ve replaced the defaults shown in this table.

    Parameter Value
    "puppet_enterprise::activity_service_regular_db_user": "pe-activity"
    "puppet_enterprise::activity_service_migration_db_user": "pe-activity"
    "puppet_enterprise::classifier_service_regular_db_user": "pe-classifier"
    "puppet_enterprise::classifier_service_migration_db_user": "pe-classifier"
    "puppet_enterprise::orchestrator_service_regular_db_user": "pe-orchestrator"
    "puppet_enterprise::orchestrator_service_migration_db_user": "pe-orchestrator"
    "puppet_enterprise::rbac_service_regular_db_user": "pe-rbac"
    "puppet_enterprise::rbac_service_migration_db_user": "pe-rbac"
  5. Save and close the pe.conf file.

    The upgrade begins.

  6. If you have compile masters, upgrade your compile masters.

    When the monolithic upgrade completes, 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
    
  7. If you have ActiveMQ hubs and spokes, upgrade your ActiveMQ hubs and spokes.

    When the monolithic upgrade completes, 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
    
  8. Upgrade these additional PE infrastructure components.

Upgrade a high availability installation

To upgrade a high availability installation, you first upgrade the primary master, and then you upgrade the primary master replica.

You can upgrade from any PE version with high availability support, which began in PE 2017.5, to any subsequent version with HA.

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

Before you begin: If your master is set to noop mode (noop = true in puppet.conf on the master), remove or comment out this flag prior to upgrade. The installer fails if you attempt to upgrade in noop mode.

  1. On the primary master replica, stop these services:

    • pe-puppetdb
    • pe-puppetserver
    • pe-console-services
  2. Download and unpack the PE installation tarball: tar -xf <tarball>

    You need about 1 GB of space to untar the installer.

  3. From the installer directory, run the installer. The steps vary depending on the path you choose.

    • To use a pe.conf file that already exists, run the upgrade with the -c flag pointed at the pe.conf file.

      sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
      

      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.

      Warning: If you’re using a pre-populated file, be sure you’ve set the parameters correctly as detailed in the following steps.

    • To have the installer open a copy of pe.conf for you to edit and upgrade with, run the installer without the -c flag.

      sudo ./puppet-enterprise-installer
      
  4. Set the console admin password in pe.conf.

    Parameter Value
    "console_admin_password": "<PASSWORD>" Replace <PASSWORD> with your password used to log into the PE console.

    Tip: On a monolithic upgrade, you can leave the default value of "%{::trusted.certname}" if the certname of your monolithic server matches its FQDN.

  5. If you use external PostgreSQL, set required parameters in pe.conf.

    Important: Don’t use single quotes on parameter values. Use double quotes as shown in the examples. Substitute the database user names if you’ve replaced the defaults shown in this table.

    Parameter Value
    "puppet_enterprise::activity_service_regular_db_user": "pe-activity"
    "puppet_enterprise::activity_service_migration_db_user": "pe-activity"
    "puppet_enterprise::classifier_service_regular_db_user": "pe-classifier"
    "puppet_enterprise::classifier_service_migration_db_user": "pe-classifier"
    "puppet_enterprise::orchestrator_service_regular_db_user": "pe-orchestrator"
    "puppet_enterprise::orchestrator_service_migration_db_user": "pe-orchestrator"
    "puppet_enterprise::rbac_service_regular_db_user": "pe-rbac"
    "puppet_enterprise::rbac_service_migration_db_user": "pe-rbac"
  6. Save and close the pe.conf file.

    The upgrade begins.

  7. When the upgrade is complete on the primary master, run puppet agent -t.

  8. On the primary master replica, 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.

  9. If you have compile masters, upgrade your compile masters.

    When the monolithic upgrade completes, 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
    
  10. If you have ActiveMQ hubs and spokes, upgrade your ActiveMQ hubs and spokes.

When the monolithic upgrade completes, SSH into each hub and spoke and run:

~~~ /opt/puppetlabs/puppet/bin/curl –cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://:8140/packages/current/upgrade.bash | sudo bash ~~~

  1. Upgrade these additional PE infrastructure components.

Upgrade options

When you run the upgrade, you can pass additional flags to control the upgrade.

As described above, the syntax for the upgrader with a specified pe.conf file is:

sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

When you use the -c option, the pe.conf file name with full path is required. The command will quit with an error message if you omit it.

When you use the -c option, you can also use the following options:

Option Definition
-D The installer will display debugging information
-q The installer will run in quiet mode. The installation process will not be displayed. If errors occur during the installation, the command will quit with an error message.
-y The installer/upgrader will will run automatically using whatever pe.conf is in /etc/puppetlabs/enterprise/conf.d/. Note that if this file is incorrect, your upgrade will fail.
-V The installer will display very verbose debugging information.
-h The installer will display help information.

Checking for updates

Check here to find out the latest maintenance release of Puppet Enterprise. To see the version of PE you are currently using, run puppet --version on the command line.

Note: By default, the Puppet master checks for updates whenever the pe-puppetserver service restarts. As part of the check, it passes some basic, anonymous information to Puppet’s servers. This behavior can be disabled if need be. See Disabling update checking for details on what is collected and how to disable checking.

↑ Back to top