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.

JRuby instance flushing may cause a memory leak

JRuby instance flushing may cause a memory leak for many, if not all, of our users. We recommend that users who have set their max-requests-per-instance settings for 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_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 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.