Upgrading Puppet Enterprise

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
2021.0 (latest) You're up to date!
2019.8.z latest
2019.y 2019.8.z
2018.1.2 or later

2018.1.3 or later with disaster recovery

2019.8.z You must have version 2018.1.2 or later in order to complete prerequisites for upgrade to 2019.8.z.

With disaster recovery enabled, you must have version 2018.1.3 in order to upgrade to 2019.8.z. Alternatively, you can forget and then recreate your replica after upgrade.

2018.1.0 or 2018.1.1 2018.1.z

Upgrade cautions

These are the major changes to PE since the last long-term support release, 2019.8. Review these recommendations and plan accordingly before upgrading to this version.

Platforms removed in 2021.0

Several agent platforms that were previously deprecated have been removed in PE 2021.0.

Before upgrading to this version, remove the pe_repo::platform class for these operating systems from the PE Master node group in the console, and from your code and Hiera.

  • AIX 6.1
  • Enterprise Linux 4
  • Enterprise Linux 6, 7 s390x
  • Fedora 26, 27, 28, 29
  • Mac OS X 10.9, 10.12, 10.13
  • SUSE Linux Enterprise Server 11, 12 s390x

Test modules before upgrade

To ensure that your modules 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.
Results

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

Upgrade PE

Upgrade PE infrastructure components to get the latest features and fixes. Follow the upgrade instructions for your installation type to ensure you upgrade components in the correct order.

Before you begin
Review the upgrade cautions for major changes to architecture and infrastructure components which might affect your upgrade.

Upgrade a standard installation

To upgrade a standard installation, run the PE installer on your primary server, and then upgrade any additional components.

Before you begin

Back up your PE installation.

If you're upgrading a replica, ensure you have a valid admin RBAC token. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

Remove from the console (in the PE Master node group), Hiera, or pe.conf any agent_version parameters that you've set in the pe_repo class that matches your infrastructure nodes. Doing so ensures that upgrade isn't blocked by attempting to download a non-default agent version for your infrastructure OS and architecture.

  1. Optional: Speed upgrade by cleaning up PuppetDB reports. On your primary server, run /opt/puppetlabs/bin/puppetdb delete-reports
    If the command fails to execute, you're likely using a version of PuppetDB that doesn't yet include the command. See Upgrade cautions for manual steps.
  2. Download the tarball appropriate to your operating system and architecture.
  3. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  4. From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
    sudo ./puppet-enterprise-installer
    • If you want 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. Upgrade these additional PE infrastructure components.
    • Agents

    • PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.

  6. In disaster recovery installations, upgrade your replica.

    The replica is temporarily unavailable to serve as backup during this step, so time upgrading your replica to minimize risk.

    1. On your primary server logged in as root, run: puppet infrastructure upgrade replica <REPLICA_FQDN>
      To specify the location of an authentication token other than the default: puppet infrastructure upgrade replica <REPLICA_FQDN> --token-file <PATH_TO_TOKEN>
    2. After the replica upgrade successfully completes, verify that primary and replica services are operational. On your primary server, run: /opt/puppetlabs/bin/puppet-infra status
    3. If your replica reports errors, reinitialize the replica. On your replica, run: /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
  7. Optional: Remove old PE packages from your infrastructure nodes: puppet infrastructure run remove_old_pe_packages pe_version=current
    For pe_version, you can specify a SHA, a version number, or current. All packages older than the specified version are removed.

Upgrade a large installation

To upgrade a large installation, run the PE installer on your primary server, and then upgrade compilers and any additional components.

Before you begin

Back up your PE installation.

Ensure you have a valid admin RBAC token in order to upgrade compilers or a replica. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

Remove from the console (in the PE Master node group), Hiera, or pe.conf any agent_version parameters that you've set in the pe_repo class that matches your infrastructure nodes. Doing so ensures that upgrade isn't blocked by attempting to download a non-default agent version for your infrastructure OS and architecture.

  1. Optional: Speed upgrade by cleaning up PuppetDB reports. On your primary server, run /opt/puppetlabs/bin/puppetdb delete-reports
    If the command fails to execute, you're likely using a version of PuppetDB that doesn't yet include the command. See Upgrade cautions for manual steps.
  2. Download the tarball appropriate to your operating system and architecture.
  3. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  4. From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
    sudo ./puppet-enterprise-installer
    • If you want 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. To upgrade compilers, on your primary server logged in as root, run: puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
    • To upgrade all compilers simultaneously: puppet infrastructure upgrade compiler --all
    • To specify the location of an authentication token other than the default: puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
  6. Upgrade these additional PE infrastructure components.
    • Agents

    • PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.

  7. In disaster recovery installations, upgrade your replica.

    The replica is temporarily unavailable to serve as backup during this step, so time upgrading your replica to minimize risk.

    1. On your primary server logged in as root, run: puppet infrastructure upgrade replica <REPLICA_FQDN>
      To specify the location of an authentication token other than the default: puppet infrastructure upgrade replica <REPLICA_FQDN> --token-file <PATH_TO_TOKEN>
    2. After the replica upgrade successfully completes, verify that primary and replica services are operational. On your primary server, run: /opt/puppetlabs/bin/puppet-infra status
    3. If your replica reports errors, reinitialize the replica. On your replica, run: /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
  8. Optional: Remove old PE packages from your infrastructure nodes: puppet infrastructure run remove_old_pe_packages pe_version=current
    For pe_version, you can specify a SHA, a version number, or current. All packages older than the specified version are removed.
What to do next

Optionally convert legacy compilers to the new style compiler running the PuppetDB service.

Upgrade an extra-large installation

For help upgrading an extra-large installation, reach out to your technical account manager.

Upgrade a standalone PE-PostgreSQL installation

To upgrade a large installation with standalone PE-PostgreSQL, run the PE installer first on your PE-PostgreSQL node, then on your primary server, and then upgrade any additional components.

Before you begin

Back up your PE installation.

Ensure you have a valid admin RBAC token in order to upgrade compilers. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

Remove from the console (in the PE Master node group), Hiera, or pe.conf any agent_version parameters that you've set in the pe_repo class that matches your infrastructure nodes. Doing so ensures that upgrade isn't blocked by attempting to download a non-default agent version for your infrastructure OS and architecture.

  1. Optional: Speed upgrade by cleaning up PuppetDB reports. On your primary server, run /opt/puppetlabs/bin/puppetdb delete-reports
    If the command fails to execute, you're likely using a version of PuppetDB that doesn't yet include the command. See Upgrade cautions for manual steps.
  2. Download the tarball appropriate to your operating system and architecture.
  3. Unpack the installation tarball: tar -xf <tarball>
    You need about 1 GB of space to untar the installer.
  4. Upgrade your PostgreSQL node.
    1. Ensure that the pe.conf file on your PostgreSQL node is up to date by running puppet infrastructure recover_configuration on your primary server, and then copying /etc/puppetlabs/enterprise/conf.d to the PostgreSQL node.
    2. Copy the installation tarball to the PostgreSQL node, and from the installer directory, run the installer: sudo ./puppet-enterprise-installer
  5. From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
    sudo ./puppet-enterprise-installer
    • If you want 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.

  6. To upgrade compilers, on your primary server logged in as root, run: puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
    • To upgrade all compilers simultaneously: puppet infrastructure upgrade compiler --all
    • To specify the location of an authentication token other than the default: puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
  7. Upgrade these additional PE infrastructure components.
    • Agents

    • PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.

  8. Optional: Remove old PE packages from your infrastructure nodes: puppet infrastructure run remove_old_pe_packages pe_version=current
    For pe_version, you can specify a SHA, a version number, or current. All packages older than the specified version are removed.
What to do next

Optionally convert legacy compilers to the new style compiler running the PuppetDB service.