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.7.5 (LTS) | You're up to date! | If you're on the most recent LTS release, you can stay here or upgrade to the STS. |
2019.8.z or any 2021.y | 2021.7.z (LTS) | Before upgrading to 2021.7.z, you might want to read about What's new since PE 2019.8. |
2019.y | 2019.8.12 | |
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 previous long-term support release, 2019.8. Review these recommendations and plan accordingly before upgrading to this version.
FIPS-enabled PE 2021.7 and later can't use the default system cert store
PE 2021.7 and later FIPS builds can't use the default
system cert store, which is used automatically with some reporting services. This
setting is configured by the report_include_system_store
Puppet parameter that ships with PE.
Removing the puppet-cacerts
file (located at /opt/puppetlabs/puppet/ssl/puppet-cacerts
) can allow a
report processor that eagerly loads the system store to continue with a warning that
the file is missing.
If HTTP clients require external certs, we recommend using a custom cert store
containing only the necessary certs. You can create this cert store by concatenating
existing pem
files and configuring the ssl_trust_store
Puppet parameter to point to the new cert
store.
PostgreSQL 14 upgrade in PE 2021.6
PE 2021.6.0 upgrades pe-postgresql
from version 11 to version 14. This upgrade involves a datastore migration that requires
extra disk space (110% of the current PostgreSQL 11
datastore) and extra time to upgrade (roughly two to four minutes of additional time per
10GB of datastore size). The installer issues a warning and cancels the upgrade if there is
insufficient space.
To check your PostgreSQL installation size and the size
and number of bytes available for the partition, run facter -p
pe_postgresql_info
on the node that runs the pe-postgresql
service (this is either your primary server or a separate node that manages your PostgreSQL database).
To speed the migration and optimize queries, clean up the PE-PostgreSQL database prior to upgrading by applying
the pe_databases module to nodes running the
pe-postgresql
service. This module is installed with PE versions 2021.3 and later, but you must enable it by
setting the puppet_enterprise::enable_database_maintenance
parameter to true
. For best results, apply the module at least one week
prior to upgrade to allow the module's maintenance schedule enough time to clean all
databases.
Optionally, after upgrading, you can remove packages and directories from older PostgreSQL versions by running puppet
infrastructure run remove_old_postgresql_versions
. If applicable, the
installer prompts you to complete the cleanup.
CONCURRENTLY
with PostgreSQL 14.0 through 14.3. If you do, make sure to
REINDEX
without using CONCURRENTLY
.Platforms removed in 2021.0 and later
Several agent platforms that were previously deprecated have been removed in PE 2021.0 and later.
pe_repo::platform
class for these operating systems from the
PE Master node group in the console, and from your code and
Hiera. - Platforms removed in 2021.0
- Removed agent platforms
- AIX 6.1
- Platforms removed in 2021.7.5
- Removed agent platforms
- CentOS 7 aarch64
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.
Configure non-production environment for infrastructure nodes
If your infrastructure nodes are in an environment other than production
, you must manually configure PE to
use your chosen environment before you upgrade.
production
.pe.conf
, set both of these parameters to the
environment your infrastructure nodes are in:
pe_install::install::classification::pe_node_group_environment
puppet_enterprise::master::recover_configuration::pe_environment
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.
In Hiera, pe.conf
, or the console (in the PE Master node
group), remove any agent_version
parameters you set
in the pe_repo
class that matches your
infrastructure nodes. This ensures the upgrade isn't blocked by attempting to
download non-default agent versions 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.
In Hiera, pe.conf
, or the console (in the PE Master node
group), remove any agent_version
parameters you set
in the pe_repo
class that matches your
infrastructure nodes. This ensures the upgrade isn't blocked by attempting to
download non-default agent versions for your infrastructure OS and architecture.
Optionally convert legacy compilers to the new style compiler running the PuppetDB service.
Upgrade an extra-large installation
You can use the PEADM module to upgrade extra-large installations. Contact your technical account manager for additional support.
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.
In Hiera, pe.conf
, or the console (in the PE Master node
group), remove any agent_version
parameters you set
in the pe_repo
class that matches your
infrastructure nodes. This ensures the upgrade isn't blocked by attempting to
download non-default agent versions 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 Puppet Enterprise (PE) installation that relies on an unmanaged PostgreSQL database, you must upgrade PostgreSQL to version 14 and ensure that your PostgreSQL database roles, privileges, extensions, and configuration are up to date with the most recent version of PE. Then, proceed with the PE upgrade.
Ensure that you have a valid role-based access control (RBAC) admin token to upgrade compilers (for example, Generate a token using puppet-access).
In Hiera, pe.conf
, or the console (in the PE Master node
group), remove any agent_version
parameters you set
in the pe_repo
class that matches your
infrastructure nodes. This ensures the upgrade isn't blocked by attempting to
download non-default agent versions for your infrastructure OS and architecture.
Optionally, convert existing compilers to the new style compiler running the PuppetDB service.
CONCURRENTLY
with PostgreSQL 14.0 through 14.3. If you do, ensure that
you REINDEX
without using CONCURRENTLY
.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.
For standard installations with disaster recovery, follow the steps to Upgrade a standard installation.
For large installations with or without disaster recovery, follow the steps to Upgrade a large installation.
For all extra-large installations or any size installation where either upgrading or migrating is not possible, contact your technical account manager.
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.