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.

The following table lists the unmapped legacy facts that cannot be automatically converted. If any of these unmapped legacy facts are included in any Puppet code you use, you must remove the facts or manually replace them with a close equivalent structured fact.


Unmapped 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

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.