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
2023.5 (latest)	You're up to date!
2021.7.z	latest	Review the upgrade cautions and other information on this page.
2021.y or 2019.8.z	2021.7.z	For important information about this upgrade, refer to Upgrading Puppet Enterprise in the 2021.7.z documentation.
2019.y	2019.8.12
Earlier versions	Refer to Upgrade paths in the 2019.8.z documentation.

Upgrade cautions

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

r10k upgrade in PE 2023.4 and later

In PE 2023.4 and later, r10k is updated to version 4.0, which includes new dependencies for Puppet 8. Before attempting upgrade, review the following information and make any necessary changes to your settings, Puppetfile Ruby code, local repo permissions, and known_hosts file.

Starting in PE 2023.4, if you use Code Manager or r10k, with SSH protocol for remote Git repository access, you must set up SSH host key verification.
Important: Omitting to set up SSH host key verification for Code Manager or r10k causes code management and deployment processes to fail.

To manage the known_hosts file and enable host key verification for Code Manager or r10k, you must define the puppet_enterprise::profile::master::r10k_known_hosts parameter with an array of hashes specifying "name", "type", and"key" with your hostname, key type, and public key, respectively.
For more information about how to set up SSH host key verification, see the following topics:
- If you use Code Manager, see Enable Code Manager.
- If you use r10k as your code deployment tool, see Configure r10k.
Starting in version 4.0, r10k no longer accesses repos on local file systems not owned by the pe-puppet user. If you use r10k on the local file system, ensure that your control repo and module repos are owned by the pe-puppet user.
Git-based modules no longer have a default reference such as master. Now, when pointing to Git-based modules, you must specify the branches or revisions. Alternatively, you can use the global default_ref setting to manually set your default reference.
By default, the exclude_spec setting is now set to true so that spec directories are automatically deleted from Git-based sources.
If you use your own Ruby install, note that r10k 4.0 drops support for Ruby versions 2.3, 2.4, and 2.5.
The purge_whitelist setting has been removed. Instead, you can use purge_allowlist when manually configuring r10k 4.0.
The protected method basedir is removed from the Puppetfile @librarian instance. Protected methods should no longer be used in Puppetfile. However, if you require a temporary workaround, you can use the environment_name accessor.

Logback upgrade in PE 2023.4 and later

Starting in PE 2023.4, logback is upgraded to version 1.3.7. Using a Java argument, the logappender variable is now set by default to F1 for all projects. If you customize this setting, to avoid disruptions in logging, ensure that all logappender variable references are correctly defined. Using invalid appender references or omitting to use a reference will cause logback version 1.3.7 to stop logging.

Java 17 upgrade in PE 2023.0 and later

PE 2023.0 and later includes an upgrade from Java version 11 to version 17. With this upgrade, PE uses the G1 garbage collector by default, instead of Parallel.

Thoroughly test PE 2023.y in a non-production environment before upgrading if you customized PE Java services or you use plug-ins that include Java code.

FIPS-enabled PE 2023.0 and later can't use the default system cert store

FIPS-compliant builds running PE 2023.0 and later 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.

Puppet upgrade in 2023.4 and later

PE 2023.4 introduced a new major version of Puppet. Consider the information presented here about changes in Puppet 8 that might impact your Puppet Enterprise installation, and plan accordingly before upgrading.

Legacy facts no longer collected or sent to Puppet Server

Puppet 8 completes the transition away from legacy facts, which were deprecated in Puppet 7. Starting in Puppet 8, legacy facts are no longer collected or sent to the Puppet Server. Instead of using legacy facts, which were written as key-value pairs, Puppet 8 now uses structured facts, which are array and hash data structures.

Starting in PE 2023.4, to help ensure that nodes are classified correctly, the PE node classifier service examines your node group rules and automatically replaces most legacy facts with exact equivalent structured facts.

Restriction: Some legacy facts cannot be mapped to an exact equivalent structured fact, so they must be manually removed or replaced by a close equivalent structured fact. The classifier generates warning messages in the logs prompting you to remove or replace any unmappable legacy facts that are included in your node group rules. For a list of unmappable legacy facts together with close equivalent structured facts you can use, see the table below.

Important: Starting in PE2023.4, the installer examines your existing node group rules and if any unmappable legacy facts are found, the installation process stops with a warning. To proceed with installation, you can manually replace or remove unmappable legacy facts and re-run the installer.

To avoid disruptions associated with legacy facts, take the following actions as required.

If you have Puppet code containing legacy facts, you can use the legacy_facts plugin in the puppet-lint tool to automatically convert any legacy facts that map to an exact equivalent structured fact.
If legacy facts are referenced in your Embedded Ruby (ERB) templates, your Embedded Puppet (EPP) templates, or in your Hiera configuration file, you must manually find those legacy facts and either remove them or replace them with exact or close equivalent structured facts.
If you plan to use any of the /v*/classified/nodes endpoints, you must enter structured facts to obtain accurate results.
If unmappable legacy facts are included in any of your PE node group rules or in any Puppet code you use, you must manually remove those legacy facts or replace them with close equivalent structured facts. See the table below for more information.

The following table lists the unmappable legacy facts that cannot be automatically converted by the PE classifier or the legacy_facts plugin in the puppet-lint tool. You can manually replace these unmappable legacy facts with their respective close equivalent structured facts.


Unmappable legacy fact	Close equivalent structured facts
`memoryfree_mb` Returned a double specifying the size of the free system memory, in mebibytes.	`$facts['memory']['system'][available']` or `$facts['memory']['system']['available_bytes']` See Facter documentation on memory.
`memorysize_mb` Returned a double specifying the size of the total system memory, in mebibytes.	`$facts['memory']['system']['total']` or `$facts['memory']['system']['total_bytes']` See Facter documentation on memory.
`swapfree_mb` Returned a string specifying the size of the free swap memory, in mebibytes.	`$facts['memory']['swap']['available']` or `$facts['memory']['swap']['available_bytes']` See Facter documentation on memory.
`swapsize_mb` Returned a string specifying the size of the total swap memory, in mebibytes.	`$facts['memory']['swap']['used']` or `$facts['memory']['swap']['used_bytes']` See Facter documentation on memory.
`blockdevices` Returned a string containing all block devices separated by a comma.	Can be replicated using puppetlabs/stdlib and the following: `join(keys($facts['disks']), ',')`
`interfaces` Returned a string containing all interfaces separated by a comma.	Can be replicated using puppetlabs/stdlib and the following: `join(keys($facts['networking']['interfaces']), ',')`
`zones` Returned a string containing all zone names separated by a comma.	Can be replicated using puppetlabs/stdlib and the following: `join(keys($facts['solaris_zones']['zones']), ',')`
`sshfp_dsa` Returned a string containing both the SHA1 and SHA256 fingerprint for the DSA algorithm.	Can be replicated using the following string: `"$facts['ssh']['dsa']['fingerprints']['sha1'] $facts['ssh']['dsa']['fingerprints']['sha256']"` See Facter documentation on SSH.
`sshfp_ecdsa` Returned a string containing both the SHA1 and SHA256 fingerprint for the ECDSA algorithm.	Can be replicated using the following string: `"$facts['ssh']['ecdsa']['fingerprints']['sha1'] $facts['ssh']['ecdsa']['fingerprints']['sha256']"` See Facter documentation on SSH.
`sshfp_ed25519` Returned a string containing both the SHA1 and SHA256 fingerprint for the Ed25519 algorithm.	Can be replicated using the following string: `"$facts['ssh']['ed25519']['fingerprints']['sha1'] $facts['ssh']['ed25519']['fingerprints']['sha256']"` See Facter documentation on SSH.
`sshfp_rsa` Returned a string containing both the SHA1 and SHA256 fingerprint for the RSA algorithm.	Can be replicated using the following string: `"$facts['ssh']['rsa']['fingerprints']['sha1'] $facts['ssh']['rsa']['fingerprints']['sha256']"` See Facter documentation on SSH.

Strict mode enabled by default

Starting in Puppet 8, strict validation is enabled by default through the strict=error and strict_variables=true settings in puppet.conf. With these default settings, if your Puppet code does not conform to strict rules, then catalog compilation fails with an error. To avoid disruption, consider the following points and manually update your code where necessary.

Automatic type coercion is not allowed in strict mode. For example, a string such as “1”+1 in your Puppet code cannot be automatically converted to a numeric. For more information about automatic type coercion see, Automatic coercion in the Open Source Puppet documentation.
If your Hiera code references legacy facts in top-level variables, then those variables cannot be defined because Puppet agents no longer collect or send legacy facts. When top-level variables are undefined, strict validation causes Hiera lookups to fail. For example, when strict mode is enabled, a lookup error occurs with the following hierarchy:
```
hierarchy:
  - name: "osfamily"
    path: "%{osfamily}.yaml"
```
To avoid Hiera lookup failures, replace the legacy fact with the equivalent structured fact as follows:
```
hierarchy:
  - name: "osfamily"
    path: "%{facts.os.family}.yaml".
```
If a hierarchy currently references an optional fact, you must use the facts hash as follows to ensure that the Hiera lookup proceeds to the common layer when agents omit the fact:
```
hierarchy:
  - name: "optional"
    path: "%{facts.optional}.yaml"
  - name: "common"
    path: "common.yaml".
```

If you want to permit automatic type coercions, you can disable strict mode in the console:

Click Node groups > PE Infrastructure > PE Agent.
Select the Classes tab and locate the puppet_enterprise::profile::agent class.
From the Parameter name dropdown, select strict and enter "warning" as the value.
Click Add to node group and commit your changes.

Alternatively, you can disable strict mode using the CLI:

On the Puppet Server host, run puppet config set strict warning --section main.
Restart the pe-puppetserver service by running systemctl restart pe-puppetserver.

Important: If you disable strict mode, you must still ensure that you remove all references to legacy facts from your global layer, environment layer, and module layer hiera.yaml files. Otherwise, Hiera lookups will return corrupted data to compilers.

Ruby version upgrade

The upgrade to Ruby 3.2 in Puppet 8 might result in compatibility issues that affect Puppet extensions in your code. To check compatibility, use the latest version of PDK to update and test your modules.

OpenSSL version upgrade

Puppet 8 includes OpenSSL 3.0. This upgrade might result in compatibility issues when the agent is connecting to other servers in your environment. To avoid SSL errors, ensure that the OpenSSL version used by your servers is updated to OpenSSL 3.0.

Hiera 3 gem removed

All deprecated Hiera 3 functionality is implemented in Hiera 5, which is included in Puppet 8. If your PE infrastructure relies on a custom Hiera 3 backend, you must manually install the Hiera 3 gem on all Puppet Server hosts or convert your backend to Hiera 5. For further information, see Upgrading to Hiera 5.

PSON removed

In previous releases, Pure JavaScript Open Notation (PSON) was used in Puppet to serialize data for transmission. PSON was deprecated in Puppet 7 and is removed in Puppet 8.

Platforms removed in 2023.0 and later

Platforms that were previously deprecated have been removed in PE 2023.0 and later.

Before upgrading, 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.

Platforms removed in 2023.0
Removed primary server platforms: CentOS 8
Removed agent platforms: CentOS 8; Debian 9; Fedora 32; Fedora 34; Ubuntu 16.04
Removed client tools platforms: No client tools platforms removed.
Removed patching platforms: Debian 9; Fedora 34

Platforms removed in 2023.4
Removed agent platforms: AIX 7.1; CentOS 6; CentOS 7 aarch64; macOS 10.15; Oracle Linux 6; Oracle Linux 7 aarch64; Red Hat Enterprise Linux (RHEL) 6; Red Hat Enterprise Linux (RHEL) 7 aarch64; Scientific Linux 6; Scientific Linux 7 aarch64; Solaris 10
Removed client tool platforms: CentOS 6; macOS 10.15; Oracle Linux 6; Red Hat Enterprise Linux (RHEL) 6; Scientific Linux 6

For information about supported platforms, see:

Test modules before upgrading

Before upgrading, make sure your modules work with the newest PE version by using the Puppet Development Kit (PDK) to update and test your modules.

If you're already using PDK, your modules should pass validation and unit tests with your currently installed version of PDK.

Updating PDK with each new release ensures module compatibility with new versions of PE.

Download and install PDK. If you already have PDK installed, this updates PDK to its latest version. For detailed instructions and download links, go to Installing PDK in the PDK documentation.
If you have not previously used PDK with your modules, convert them to a PDK-compatible format. This makes changes to your module to allow validation and unit testing with PDK. For important information, go to Converting modules in the PDK documentation.
For example, from within the module directory, run: pdk convert
If your modules are already compatible with PDK, update them to the latest module template. If you converted modules in the previous step, you do not need to update the template. To learn more about updating, go to Updating modules with changes to the template in the PDK documentation.
For example, from within the module directory, run: pdk update
Validate and run unit tests for each module, specifying the version of PE you are upgrading to. When specifying a PE version, you must included at least the first two parts of the release number, such as 2023.0. For information about module validations and testing, go to Validating and testing modules in the PDK 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 then runs the unit tests that you write. It does not create unit tests for your module.
If your module fails validation or unit tests, make any necessary changes to your code and retest.

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. Coordinate upgrades to ensure all infrastructure nodes are upgraded in a timely manner, because agent runs and replication fail if infrastructure nodes are running a different agent version than the primary server.

Before you begin

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.

Important: Only do this procedure if your infrastructure nodes are in an environment that is not production.

In 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.

Before you begin

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.

Download the tarball for your operating system and architecture. Optionally, you can Verify the installation package.
Run tar -xf <TARBALL> to unpack the installation tarball.
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run sudo ./puppet-enterprise-installer to start the installer, and then follow the CLI instructions to complete your server upgrade.
To specify a different pe.conf file than the existing file, use the -c flag as shown here:
```
sudo ./puppet-enterprise-installer -c <FULL_PATH_TO_pe.conf>
```
This flag tells the installer to backup the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a new pe.conf file at /etc/puppetlabs/enterprise/conf.d/pe.conf.
Upgrade the following additional PE infrastructure components:
- Agents
- PE client tools: On unmanaged nodes, you must re-install the client tools version that matches the PE version you upgraded to. On managed nodes and infrastructure nodes, client tools are automatically updated when you upgrade PE.
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:
```
sudo puppet infrastructure upgrade replica <REPLICA_FQDN>
```
  If you want to specify an authentication token other than the default, run:
```
sudo 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:
```
sudo /opt/puppetlabs/bin/puppet-infra status
```
3. If your replica reports errors, reinitialize the replica. On your replica, run:
```
sudo /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
```
Optional: Remove previous PE packages from all infrastructure nodes. On your primary server, run: puppet infrastructure run remove_old_pe_packages
All packages earlier than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER> to the command.

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.

Download the tarball for your operating system and architecture. Optionally, you can Verify the installation package.
Run tar -xf <TARBALL> to unpack the installation tarball.
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run sudo ./puppet-enterprise-installer to start the installer, and then follow the CLI instructions to complete your server upgrade.
To specify a different pe.conf file than the existing file, use the -c flag as shown here:
```
sudo ./puppet-enterprise-installer -c <FULL_PATH_TO_pe.conf>
```
This flag tells the installer to backup the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a new pe.conf file at /etc/puppetlabs/enterprise/conf.d/pe.conf.
To upgrade compilers, log in to your primary server as root and run one of these commands:
- To upgrade specific compilers, run:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
```
- To upgrade all compilers simultaneously, run:
```
sudo puppet infrastructure upgrade compiler --all
```
- To specify an authentication token location other than the default location, include --token-file <PATH_TO_TOKEN> in the command as shown here:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
```
Upgrade the following additional PE infrastructure components:
- Agents
- PE client tools: On unmanaged nodes, you must re-install the client tools version that matches the PE version you upgraded to. On managed nodes and infrastructure nodes, client tools are automatically updated when you upgrade PE.
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:
```
sudo puppet infrastructure upgrade replica <REPLICA_FQDN>
```
  If you want to specify an authentication token other than the default, run:
```
sudo 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:
```
sudo /opt/puppetlabs/bin/puppet-infra status
```
3. If your replica reports errors, reinitialize the replica. On your replica, run:
```
sudo /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
```
Optional: Remove previous PE packages from all infrastructure nodes. On your primary server, run: puppet infrastructure run remove_old_pe_packages
All packages earlier than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER> to the command.

What to do next

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.

Before you begin

Back up your PE installation.

Ensure you have a valid admin RBAC token in order to upgrade compilers.

Download the tarball for your operating system and architecture. Optionally, you can Verify the installation package.
Run tar -xf <TARBALL> to unpack the installation tarball.
You need about 1 GB of space to untar the installer.
Upgrade your PostgreSQL node.
1. Ensure that the user_data.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
From the installer directory on your primary server, run sudo ./puppet-enterprise-installer to start the installer, and then follow the CLI instructions to complete your server upgrade.
To specify a different pe.conf file than the existing file, use the -c flag as shown here:
```
sudo ./puppet-enterprise-installer -c <FULL_PATH_TO_pe.conf>
```
This flag tells the installer to backup the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a new pe.conf file at /etc/puppetlabs/enterprise/conf.d/pe.conf.
To upgrade compilers, log in to your primary server as root and run one of these commands:
- To upgrade specific compilers, run:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
```
- To upgrade all compilers simultaneously, run:
```
sudo puppet infrastructure upgrade compiler --all
```
- To specify an authentication token location other than the default location, include --token-file <PATH_TO_TOKEN> in the command as shown here:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
```
Upgrade the following additional PE infrastructure components:
- Agents
- PE client tools: On unmanaged nodes, you must re-install the client tools version that matches the PE version you upgraded to. On managed nodes and infrastructure nodes, client tools are automatically updated when you upgrade PE.
Optional: Remove previous PE packages from all infrastructure nodes. On your primary server, run: puppet infrastructure run remove_old_pe_packages
All packages earlier than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER> to the command.

What to do next

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

Upgrade an unmanaged PostgreSQL installation

You can upgrade a Puppet Enterprise (PE) installation that relies on an unmanaged PostgreSQL database.

Restriction: These steps assume you are upgrading to PE 2023.0 from PE 2021.7.z. Due to a significant PostgreSQL upgrade in PE 2021.6, if you want to upgrade from 2021.6 or earlier, you must follow the instructions linked in the Upgrade paths topic to upgrade from 2021.6 or earlier to 2021.7.z before continuing to 2023.0.

Download the tarball for your operating system and architecture. Optionally, you can Verify the installation package.
Run tar -xf <TARBALL> to unpack the installation tarball.
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run sudo ./puppet-enterprise-installer -s to start the installer, and then follow the CLI instructions to complete your server upgrade.
- The -s flag tells the installer to skip database checks.
- To specify a different pe.conf file than the existing file, use the -c flag as shown here:
```
sudo ./puppet-enterprise-installer -c <FULL_PATH_TO_pe.conf>
```
  The -c flag tells the installer to back up the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a pe.conf file at /etc/puppetlabs/enterprise/conf.d/pe.conf.
To upgrade compilers, log in to your primary server as root and run one of these commands:
- To upgrade specific compilers, run:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
```
- To upgrade all compilers simultaneously, run:
```
sudo puppet infrastructure upgrade compiler --all
```
- To specify an authentication token location other than the default location, include --token-file <PATH_TO_TOKEN> in the command as shown here:
```
sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
```
Upgrade the following additional PE infrastructure components:
- Agents
- PE client tools: On unmanaged nodes, you must re-install the client tools version that matches the PE version you upgraded to. On managed nodes and infrastructure nodes, client tools are automatically updated when you upgrade PE.
Optional: Remove previous PE packages from all infrastructure nodes. On your primary server, run: puppet infrastructure run remove_old_pe_packages
All packages earlier than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER> to the command.

What to do next

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

CAUTION: Don't use CONCURRENTLY with PostgreSQL 14.0 through 14.3. However, 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.

Restriction: Currently, we only recommend migration for standard installations without disaster recovery.

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.

Before you begin

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

Install your current PE version on a new primary server node.
Back up your existing installation.
Restore your installation on the new primary server using the backup you created.
Upgrade your new primary server to the latest PE version.
Update the server setting in your nodes' puppet.conf file to your new primary server's hostname by running:
```
sudo puppet config set server <PRIMARY_HOSTNAME>
```

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.