Upgrading from Puppet 6 to Puppet 7

Before upgrading to Puppet 7, 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 7 release notes.

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

Upgrade to Puppet 6.22.0 and run the puppet facts diff command

Note: This is the only action we recommend before you upgrade. If you do not need to see the differences between the Facter 3 and Facter 4 output, you can upgrade to Puppet 7 from any version of Puppet 6.

If you are currently using Puppet 6.21.0 or below, upgrade to Puppet 6.22.0 before you upgrade to Puppet 7, and run the puppet facts diff command to see if there are any output differences between Facter 3 and Facter 4. Puppet 6.22.0 filters out the core volatile facts and provides an --exclude flag that allows to exclude specific facts.

When you run the puppet facts diff command, the output looks something like:
> puppet facts diff
{
  "fact_with_different_values": {
    "new_value": "facter4",
    "old_value": "facter3"
  },
  "fact_not_existing_in_facter3": {
    "new_value": "facter4",
    "old_value": null
  },
  "fact_not_existing_in_facter4": {
    "new_value": null,
    "old_value": "facter3"
  }
}


new_value  - the value in Facter 4
old_value  - the value in Facter 3

Some of the differences you might see include:

  • A volatile fact that comes from a module, for example the puppet_agent_pid fact from the puppet_agent module.

  • Facts that return an Array as a value. For example the mountpoints fact has an options field. The puppet facts diff command reports these differences because the value Array can be in a different order. For example:
    # facter 3 output
> facter mountpoints./.options
[ "local", "noatime", "nobrowse", "journaled"]

# facter 4 output
> facter mountpoints./.options
[ "local", "nobrowse", "journaled", "noatime"]

      ❯ puppet facts diff
               "mountpoints./.options.2": {
          "new_value": "nobrowse",
          "old_value": "noatime"
        },
        "mountpoints./.options.3": {
          "new_value": "journaled",
          "old_value": "nobrowse"
        },
        "mountpoints./.options.4": {
          "new_value": "noatime",
          "old_value": "journaled"
        }
  • New facts. For example, Facter 4 added cores and threads information to the processors fact. These return the following diff output: 
    {
  "processors.cores": {
    "new_value": 2,
    "old_value": null
  },
  "processors.threads": {
    "new_value": 1,
    "old_value": null
  }
}
If you see differences caused by a Facter 3 known issue, you can use the --exclude flag to remove them from your output, so that you only see the differences relevant to you. For example: 
# using --exclude flag to filter out multiple facts
> puppet facts diff --exclude "^fact1$|^fact2$"
{
  "fact3": {
    "new_value": null,
    "old_value": "facter3"
  }
}
The puppet facts diff command is also available as a task in the puppetlabs-puppet_agent module version 4.5.0 or above. Starting with version 4.5.1, the exclude parameter is available. For example:
> bolt task show puppet_agent::facts_diff
puppet_agent::facts_diff
  Run the Puppet agent facts diff action

Usage
  bolt task run puppet_agent::facts_diff --targets <targets> [exclude=<value>]

Parameters
  exclude  Optional[String]
    Regex used to exclude specific facts from diff.
Note: For information on a specific fact, see the known issues and release notes for both Facter 3 and Facter 4.

Update the acl and reboot modules

If you want to use the acl and reboot modules with Puppet 7, you need to update them to the following versions:

New CA directory location

The default location of the CA directory in Puppet 7 is etc/puppetlabs/puppetserver/ca. The new location makes it harder to accidentally delete your CA. When you upgrade to Puppet 7, we do not move the CA directory for you. The puppetserver CA CLI provides a migrate command for you to move your CA directory to the new location — puppetserver ca migrate. This creates a symlink from the old CA location to the new location. The symlink provides backwards compatibility for tools still expecting the cadir to exist in the old location. In a future release, the cadir setting will be removed entirely.

The local filebucket is disabled by default

The Puppet 7 local filebucket is disabled by default as the local cache has no limit and is not automatically cleaned. To clean the local cache, run the puppet_agent::delete_local_filebucket task from the puppetlabs-puppet_agent module version 4.5.1 or above. For example: 
> bolt task show puppet_agent::delete_local_filebucket
puppet_agent::delete_local_filebucket
  Removes the local filebucket

Usage
  bolt task run puppet_agent::delete_local_filebucket --targets <targets>
  [force=<value>]

Parameters
  force  Optional[Boolean]
    ignore nonexistent files and errors

Windows win32 gems removed

Custom facts, external facts, and modules that explicitly require (or rely on Puppet to provide) win32 gems do not work in Puppet 7. These include:
  • win32-process
  • win32-service
  • win32-dir
  • win32-security
CAUTION: We are not validating the win32 gems with Ruby 2.7. If you choose to install them, expect deprecation warnings.

The win32-service gem

The win32-service gem allows you to control or create MS Windows services. The functionality that the win32-service gem provided is available in Puppet 7 with the Puppet::Util::Windows::Service class, and provides the following methods: [:send_service_control_signal, :resume, :start, :service_start_type, :service_state, :stop, :logon_account, :set_startup_configuration, :services, :exists?].

To use the Puppet::Util::Windows::Service class instead of the Win32::Service gem, make the following changes to your configuration:

  • Remove require win32/service.

  • Replace Win32::Service with Puppet::Util::Windows::Service.

If you need any other win32-service functionality — that is not provided by Puppet::Util::Windows::Service — add the following code to your manifest: 
package { 'win32-service':
  ensure   => ['0.8.8'],
  provider => 'puppet_gem',
}

This keeps the win32-service gem locked on version 0.8.8.

The win32-process gem

The win32-process gem provided Ruby’s monkey-patching Process class. Puppet 7 implements part of this functionality and exposes the following methods: [:create, :setpriority].

To use the Puppet 7 functionality instead of the win32-process gem, make the following changes to your configuration:

  • Remove require win32-process.
  • Add require 'puppet' (Windows users only).
If you need any additional win32-process functionality — that is not provided by Puppet 7 — add the following code to your manifest:
package { 'win32-process':
 ensure => ['0.7.5'],
 provider => 'puppet_gem',
}

The win32-security gem

There is no replacement provided by Puppet for the win32-security gem. Remove require 'win32-security' from your code.

If a particular module requires this gem, you can install it by adding the following code to your manifest:
package { 'win32-security':
 ensure => ['0.4.9'],
 provider => 'puppet_gem',
}

The win32-dir gem

There is no replacement for the win32-dir gem. Puppet now relies on environment variables for this functionality. Remove any require 'win32-dir' from your code and replace the Dir calls with the corresponding environment variables, if possible. For example, if you have a custom fact that references Dir::COMMON_APPDATA, replace it with the corresponding environment variable ENV['ALLUSERSPROFILE'].

If a particular module requires this gem, you can install it by adding the following code to your manifest:
package { 'win32-dir':
 ensure => ['0.4.9'],
 provider => 'puppet_gem',
}
Note: Puppet 7 has also removed the http-client and pathspec gems for all operating systems. For a full list of removed gems, see deprecations and removals.

Facter 4 dotted facts

Facter 4, which ships with Puppet 7, introduced a new way to write aggregate custom facts by using a dot notation in a fact name. Facter automatically combines the two facts and creates a structured fact. However, in Facter 4.0.52 and below, the implementation of feature is not compatible with other parts of the Puppet ecosystem, and does not give the fact the same name as Facter 3. As a result, Facter 4.1 reverted back to the way Facter 3 handled facts with dotted names. If you want to re-enable the Facter 4 behaviour — that converts a dotted fact to a structured fact — add the following setting to your manifest:
global : {
    force-dot-resolution : true
}