Upgrading Puppet Enterprise
Sections
CollapseUpgrade 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.4 (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
Puppet upgrade in 2021.0
PE 2021.0 includes a new major version of Puppet, with several changes that might impact your upgrade. For details, see Upgrading from Puppet 6 to Puppet 7.
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.
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.
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. Coordinate upgrades to ensure all infrastructure nodes are upgraded in a timely manner, because agent runs and replication fail on infrastructure nodes running a different agent version than the primary server.
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.
Back up your PE installation.
If you're upgrading a replica, ensure you have a valid admin RBAC token.
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.
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.
Back up your PE installation.
Ensure you have a valid admin RBAC token in order to upgrade compilers or a replica.
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.
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.
Back up your PE installation.
Ensure you have a valid admin RBAC token in order to upgrade compilers.
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.
Optionally convert legacy compilers to the new style compiler running the PuppetDB service.
Upgrade an unmanaged PostgreSQL installation
To upgrade a PE installation that relies on an unmanaged PostgreSQL database, ensure your PostgreSQL database includes a PuppetDB read user, then proceed with a normal PE upgrade.
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.
Optionally convert legacy compilers to the new style compiler running the PuppetDB service.
Migrate PE
As an alternative to upgrading, you can migrate your PE installation. Migrating results in little or no downtime, but it requires additional system resources because you must configure a new primary server.
Migrate a standard installation
Migrate a standard installation by standing up a new primary server, restoring it with your existing installation, upgrading it, and then pointing agents at the new primary.
Review the upgrade cautions for major changes to architecture and infrastructure components which might affect your upgrade.