Upgrade from Puppet 8 to Puppet 9

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

This list is not 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 release notes.

Starting with version 8.11.0, installation packages are in protected repositories. For more information, see Upgrading from open source Puppet to Puppet Core.
Always back up your installation before performing any upgrade.

Review updated components

To prepare for Puppet Core 9, verify that your code dependencies are compatible with updated Puppet Core 9 components. Puppet Core 9 uses JRuby 10.1. Review your code and dependencies for compatibility with the following JRuby dependencies:

  • Java Development Kit (JDK) 21 (minimum)

  • PostgreSQL 17

  • Ruby 4.0

Ensure that dependencies for your modules are also compatible with:

  • OpenSSL 3.5

Learn more:

Update custom facts

To prevent security vulnerabilities, Ruby 4.0 no longer supports opening subprocesses with Kernel.open by passing |.

For example, the following is no longer supported:

Copy 
open('| <command>') { |pipe| ... }

If you are calling this method directly in custom facts, replace it with the IO.open method.

Check compatibility for OpenSSL 3.5

OpenSSL 3.5 adds support for the post-quantum cryptography key encapsulation mechanism (PQC KEM) algorithms including ML-KEM, ML-DSA, and SLH-DSA. Get ready for the new algorithms by checking application compatibility, putting required libraries in place, validating cipher suites, and updating your development environments.

Deferred functions are pre-processed by default

In Puppet 8, preprocess_deferred was by default set to false, so deferred functions were lazily evaluated during catalog application. This behavior caused regressions in some custom types and providers, including many third-party types and providers.

In Puppet Core 9, preprocess_deferred is set to true by default, so deferred functions are processed before catalog application. This change restores the behavior used in Puppet 7. There is no change to preprocessed resources, just a change to when they are applied.

If you rely on deferred function dependencies to be run when the catalog is applied, refactor your code to work with the updated setting. PUPDOC-6047

Review FIPS changes

If you are a Puppet Enterprise customer using FIPS, Puppet Core 9 uses OpenSSL 3.1.2 as a FIPS provider; Puppet 8 continues to use OpenSSL 3.0.9 as a FIPS provider.

Learn more about OpenSSL 3.1.2.

Review customized bootstrap.cfg files

If you customized bootstrap.cfg to prevent services from starting, document the changes you made. The upgrade adds a new bootstrap.cfg file with no customizations, so you must add customization changes to the new file. The old file will remain in place and will not be overwritten.

Change to authentication for the /status/v1/services endpoint

By default, the /status/v1/services endpoint now requires an authenticated client. The /status/v1/simple endpoint remains unauthenticated for load balancer health checks.

UTF-8 default encoding on Windows

Puppet Core now uses UTF-8 as a default for external encoding on Windows platforms, aligning Puppet with the broader Windows Ruby ecosystem, which adopted UTF-8 as the default encoding starting in Ruby 3.x. Most modern versions of Windows have UTF-8 as the locale default. However, if you have Puppet configuration files, resource names, or command output that contain non-ASCII characters encoded with Windows-1252 or ISO-8859-1, ensure your output is UTF-8 before upgrading.

Test your Puppet code

Test your Puppet code to help ensure a smooth transition to Puppet Core 9. Complete the following steps:

  1. Use the Puppet Development Kit ( PDK) to run unit tests and validate your code against Puppet’s style guide.

  2. Perform syntax and style checks. Use the puppet-lint tool to check your code for syntax and style issues, to help identify and fix code that doesn’t comply with Puppet's style guide.

  3. Run unit tests to help you verify that individual components of your Puppet code work as expected. Use the puppetlabs_spec_helper gem to write and run unit tests for your Puppet modules.

  4. Use the puppet parser validate command to check your Puppet manifests for syntax errors. Run this command on your existing code to ensure there are no syntax issues.

  5. Run acceptance tests to help verify that Puppet code works correctly in a real-world environment. Use tools like Serverspec or other tools to run integration tests on your Puppet modules.

  6. Check for deprecated features. Identify deprecated features or changes that might affect your code. Update your code to remove deprecated constructs and ensure compatibility with Puppet Core 9.

  7. Set up a test environment that mirrors your production environment. Apply your Puppet code in this test environment to identify any issues before upgrading your production environment.

  8. Review and update dependencies such as Puppet modules and Ruby gems, to ensure they are compatible with Puppet Core 9. Update your metadata.json and Gemfile files to reflect the correct dependencies.

Upgrading modules for Puppet Core 9

When upgrading officially supported Puppet modules, complete these steps:

  1. Preliminary work:

    • Remove deprecated code constructs.

    • Update module code.

    • Assign datatypes to class parameters.

    • Replace legacy facts with structured facts.

    • Update code for strict mode.

  2. Update dependencies:

    • Update metadata.json and Gemfile files to ensure correct dependencies.

    • Use the pdk update command to update your module to match the most recent template.

For specific questions or next steps, contact the Puppet support team or Puppet Professional Services for help upgrading to Puppet Core 9.