Upgrade cautions
These are the major changes introduced in recent Puppet Enterprise (PE) releases. Review these recommendations and plan accordingly before upgrading.
Remove old copies of pe_r10k before upgrading
Before upgrading, if you use Code Manager or r10k, remove pe_r10k from your Puppetfile and remove any copy of the module from your control repository and from your base module directory (/etc/puppetlabs/code-staging/modules if you use Code Manager). Then deploy code so that the old copy is removed from your environments. PE ships pe_r10k 2016.2.1. If the environment that your PE infrastructure nodes use resolves an older copy, Puppet runs on the primary server, compilers, and replicas fail with a message naming the module's path and version. If this happens after you upgrade, remove the module and deploy code in the same way. Code deploys still work while Puppet runs are failing.
r10k.yaml is no longer world-readable
/etc/puppetlabs/r10k/r10k.yaml is now mode 0640, owner root, group pe-puppet. Tools that read this file as a user other than root or a member of pe-puppet, such as standalone r10k, lose access. To change the mode or group, set puppet_enterprise::master::code_management::r10k_config_mode or r10k_config_group.
Rotate existing Forge authorization tokens after upgrading
Puppet Enterprise now protects Code Manager Forge authorization tokens by handling them as sensitive values and restricting access to r10k configuration files. If your Forge authorization token was configured in an earlier version of PE, rotate the token after upgrading.
Authorization rule certificate name matching changed in PE 2023.8.13, 2025.12.1, and 2026.0.1
Authorization rules in auth.conf now match certificate names more strictly. Rules that specify a hostname match only certificates with that exact name. Wildcard rules such as *.example.com match only names under example.com and no longer match example.com itself.
If you rely on a wildcard rule to allow both a domain and its subdomains, add a separate authorization rule for the bare domain name. Review any custom auth.conf rules after upgrading to ensure they continue to provide the intended access.
Continuous Delivery 5.17.0 required when upgrading to Puppet Enterprise
In PE 2023.8.11, 2025.12.0, and 2026.0, Puppet Server requires certificate-based authentication for the /status/v1/services endpoint. Continuous Delivery for Puppet Enterprise (CD) uses this endpoint when discovering, creating, and updating PE integrations, and when running Impact Analysis. As a result, these operations can fail with HTTP 403 errors after upgrading PE.
Affected operations can include:
-
Creating a PE integration
-
Discovering PE integration settings
-
Editing an existing PE integration
-
Running Impact Analysis
Required action: Before upgrading to PE 2023.8.11, 2025.12.0, or 2026.0, upgrade Continuous Delivery for Puppet Enterprise to version 5.17.0 to avoid failures when integrating PE instances and running Impact Analysis. [CDPE-7470]
JRuby instance flushing may cause a memory leak
In PE 2025.y and 2023.8.z, JRuby instance flushing may cause a memory leak for many PE users. Due to this, since PE 2025.1 and PE 2023.8.2, the default value for the Puppet Server setting max-requests-per-instance is now 0 (which disables JRuby flushing). We recommend that users on 2025.0, 2025.1, 2023.8.0, and 2023.8.1, upgrade to the latest version. Furthermore, we recommend users who have set their max-requests-per-instance settings for Puppet Server JRuby pools to custom, non-zero values to either move them to be unmanaged i.e. accept the default value or explicitly set the default value to 0 (the new default). Please do not manually flush the JRuby pool via the HTTP API.
Update puppet_agent module to support AIX
If you use the puppet_agent module and have the agent
installed on any AIX nodes, then before you
upgrade to PE 2023.y, you must ensure that
you are using puppet_agent module version 4.18.0 or
later. This ensures that the puppet_agent module
identifies the correct directory for AIX
resources and your AIX agents function as
expected.
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. 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_hostsfile and enable host key verification for Code Manager or r10k, you must define thepuppet_enterprise::profile::master::r10k_known_hostsparameter 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-puppetuser. If you use r10k on the local file system, ensure that your control repo and module repos are owned by thepe-puppetuser. - 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 globaldefault_refsetting to manually set your default reference. - By default, the
exclude_specsetting is now set totrueso 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_whitelistsetting has been removed. Instead, you can usepurge_allowlistwhen manually configuring r10k 4.0. - The protected method
basediris removed from the Puppetfile@librarianinstance. Protected methods should no longer be used in Puppetfile. However, if you require a temporary workaround, you can use theenvironment_nameaccessor.
Logback upgrades in PE 2023.4 and later
In PE 2023.4, logback is upgraded to version 1.3.7,
and in PE 2023.6 and later, it is upgraded to version
1.3.14. 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
causes logback versions 1.3.7 and 1.3.14 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_storePuppet parameter to point to the new cert
store.






