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.6 (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.
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
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.
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
.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
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.
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, ensure your PostgreSQL database includes a PuppetDB read user, and then proceed with the PE upgrade.
Make sure you have a valid admin RBAC 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.
CONCURRENTLY
with PostgreSQL 14.0 through 14.3. If you do, make sure to
REINDEX
without using CONCURRENTLY
.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.