Upgrading from Puppet 7 to Puppet 8

Before upgrading to Puppet 8, review the following recommendations and changes so that you can plan your upgrade accordingly.

Note that this list is not intended to be exhaustive. It highlights changes that might require action after you upgrade. For a full list of changes, including all deprecations and removals, see the Puppet 8 release notes.

Important: Always back up your installation before performing any upgrade.

MRI Ruby 3.2

Puppet 8 vendors Ruby 3.2. Ruby 3.2 has several notable breaking changes that may affect Puppet extensions, such as functions, custom facts, types & providers, report processors, etc.

For a complete list visit: https://github.com/puppetlabs/puppet/wiki/Puppet-8-Compatibility#ruby-32-compatibility

OpenSSL 3.0

Puppet agent vendors OpenSSL 3.0. If an application compiles against Puppet's openssl, then the application must be recompiled when upgrading.

For more information visit https://www.openssl.org/docs/man3.0/man7/migration_guide.html

Hiera 3 component dropped

If you rely on a Hiera 3 backend (a class that extends Hiera::Backend), you must convert your backend to Hiera 5 using the steps found at https://www.puppet.com/docs/puppet/latest/hiera_migrate.html, or manually install the Hiera 3 gem on all Puppet Server hosts. This change does not affect Hiera 5, puppet lookup or the hiera_include, hiera_hash, etc set of functions.

Legacy facts

Legacy facts are no longer collected on the agent or sent to Puppet server. Since legacy facts are not available during compilation, they cannot be referenced in puppet code, ERB/EPP templates or Hiera configuration. If your puppet code uses legacy facts, there are two ways to handle them when upgrading:

The legacy_facts puppet-lint plugin can help identify and automatically correct legacy fact usage in puppet code (https://github.com/puppetlabs/puppet-lint/blob/main/lib/puppet-lint/plugins/legacy_facts/legacy_facts.rb).

If you need to keep legacy facts in your code, they can be re-enabled by setting include_legacy_facts=true in puppet.conf on each agent.

Strict mode

Strict mode is now enabled by default. If Puppet code does not conform to strict mode, then catalog compilation will fail. Examples of non-conforming code:

  • Accessing a variable without first defining it: notice($myvar)

  • Accessing a legacy fact: notice($facts['osfamily'])

  • Coercing a string into a numeric: "1" + 1

The previous behavior can be enabled by setting strict_variables=false and strict=warning in puppet.conf.