Upgrade PE using PIM

Puppet Installation Manager (PIM) supports the upgrading of Puppet Enterprise (PE) for all supported installation architectures. For an interactive experience, choose the guided upgrade process and follow the steps in your terminal. Alternatively, if you do not require guidance, you can run your upgrade from the PIM command line by passing a JSON file containing your installation parameters.

Regardless of the upgrade process you choose, you can use PIM on a jump host to upgrade PE infrastructure components on remote infrastructure nodes. Alternatively, you can upgrade PE by using PIM on your primary server. In this scenario, if you have additional infrastructure nodes that host PE components, your primary server can serve as a jump host.

PIM uses the Puppet Enterprise Administration Module (PEADM), which depends on Puppet Bolt, a tool for automating Puppet infrastructure maintenance tasks. When you use PIM to upgrade, PIM checks whether Bolt is installed and whether your current installation is configured by PEADM. If necessary, PIM provides the option to automatically install Bolt and convert your installation to a PEADM-compatible configuration, so you can proceed with upgrading.

Upgrade PE using the guided process

For an interactive experience, use the guided upgrade process. PIM fetches information about your current installation configuration and configures your upgrade accordingly.

Before you begin

Carefully review Upgrade cautions.
Check that your modules work with the new PE version. See Test modules before upgrading.
In Hiera, pe.conf, or the console (in the PE Master node group), remove any agent_version parameters you set in the pe_repo class that matches your infrastructure nodes. This ensures the upgrade isn't blocked by attempting to download non-default agent versions for your infrastructure OS and architecture.
Back up your installation.
Ensure that you have the required access to the PE infrastructure nodes in your installation:
- To upgrade PE by using PIM on your primary server, you must log in to your primary server as the root user.
- To upgrade PE components on remote infrastructure nodes, the machine running PIM must have root SSH access to those nodes.

To upgrade PE by using the PIM guided process:

Download the latest version of PIM.
Go to the Puppet Installation Manager download page and download the binary for your operating system.
Start the guided upgrade process.
In your terminal, navigate to the pim directory and run the following command:
```
./pim wizard
```
Follow the guided steps in your terminal to complete the upgrade.
If you require additional guidance during the upgrade process, you can view help content by pressing Ctrl+H.
Important: PIM uses the Puppet Enterprise Administration Module (PEADM), which depends on Puppet Bolt, a tool for automating Puppet infrastructure maintenance tasks. PIM checks whether Bolt is installed and whether your current installation is configured by PEADM. If necessary, PIM provides the option to automatically install Bolt and convert your installation to a PEADM-compatible configuration, so you can proceed with upgrading.

Upgrade PE with your defined parameters

If you do not require guidance to upgrade PE, you can specify your upgrade parameters in a JSON file. Then use PIM to start the upgrade by running a single command.

Before you begin

Carefully review Upgrade cautions.
Check that your modules work with the new PE version. See Test modules before upgrading.
In Hiera, pe.conf, or the console (in the PE Master node group), remove any agent_version parameters you set in the pe_repo class that matches your infrastructure nodes. This ensures the upgrade isn't blocked by attempting to download non-default agent versions for your infrastructure OS and architecture.
Back up your installation.
Ensure that you have the required access to the PE infrastructure nodes in your installation:
- To upgrade PE by using PIM on your primary server, you must log in to your primary server as the root user.
- To upgrade PE components on remote infrastructure nodes, the machine running PIM must have root SSH access to those nodes. You can configure SSH, or use the -b flag to pass the SSH key or SSH credentials when you run the upgrade command.
Ensure that your installation is compatible with PIM. You can proceed directly with upgrading if you installed PE using PIM or the Puppet Enterprise Administration Module (PEADM), or if you previously converted your installation for compatibility. If your installation is not compatible with PIM, you can use the PIM CLI to convert your installation and then proceed with upgrading. See Converting your installation

To upgrade PE from the PIM command line:

Download the latest version of PIM.
Go to the Puppet Installation Manager download page and download the binary for your operating system.
Create a JSON file specifying the relevant parameters for your PE installation and the version you want to upgrade to.
If you have a saved JSON file that you previously used to install or upgrade PE, you can edit that file as required and use it for your upgrade.

For examples illustrating the JSON properties required for different PE architectures, see Creating an upgrade parameters file.
Start the upgrade.
In your terminal, navigate to the pim directory and run one of the following commands, replacing parameters.json with the actual file name (including the file path, if necessary):
- To run the upgrade without debugging and without configuring SSH, use a command like the following example:
```
./pim upgrade parameters.json
```
- To enable debug logging, add -d or --debug. For example:
```
./pim upgrade parameters.json --debug
```
- To pass an SSH key or SSH credentials for accessing remote nodes, use the -b flag as shown in the following examples:
```
./pim upgrade -b user=root -b private-key=~/.ssh/ssh_key parameters.json
```
```
./pim upgrade -b user=root -b password=ssh_password parameters.json
```
Follow the CLI prompts to complete the upgrade process.

Important: PIM uses the Puppet Enterprise Administration Module (PEADM), which depends on Puppet Bolt, a tool for automating Puppet infrastructure maintenance tasks. When you run the pim upgrade command, PIM checks whether Bolt is installed and whether your current installation was configured by PEADM. If necessary, PIM provides the option to automatically install Bolt and convert your installation to a PEADM-compatible configuration, so you can proceed with upgrading. For more information on converting your installation, see Convert your installation.

Creating an upgrade parameters file

To upgrade PE from the Puppet Installation Manager (PIM) command line, you must use a JSON file containing your installation parameters and pass that file with the ./pim upgrade command. The JSON file defines your installation architecture, including the option for disaster recovery, and specifies the PE version you want to upgrade to.

Important: Creating a JSON file containing upgrade parameters is not required if you use the guided upgrade process. With the guided process, PIM automatically fetches information about your current installation configuration and configures your upgrade accordingly.

Upgrade configuration examples

The following examples illustrate how to structure the JSON file for different PE configurations.

Upgrade parameters for an extra-large architecture with disaster recovery

{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "replica_host": "pe-xl-core-2.lab1.puppet.vm",
  "replica_postgresql_host": "pe-xl-core-3.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
  "version": "2023.6.0"
}

Upgrade parameters for an extra-large architecture without disaster recovery

{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
  "version": "2023.6.0"
}

Upgrade parameters for a large architecture with disaster recovery

{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "replica_host": "pe-l-core-2.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
  "version": "2023.6.0"
}

Upgrade parameters for a large architecture without disaster recovery

{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
  "version": "2023.6.0"
}

Upgrade parameters for a standard architecture with disaster recovery

{
  "primary_host": "pe-core-0.lab1.puppet.vm",
  "replica_host": "pe-core-2.lab1.puppet.vm",
  "version": "2023.6.0"
}

Upgrade parameters for a standard architecture without disaster recovery

{
  "primary_host": "pe-core-0.lab1.puppet.vm",
  "version": "2023.6.0"
}

Converting your installation

Puppet Installation Manager (PIM) uses the Puppet Enterprise Administration Module (PEADM), which is a set of Bolt plans for deploying and managing Puppet Enterprise (PE) infrastructure. To use PIM to upgrade, you might be required to convert your installation to a PEADM-compatible configuration.

Converting your installation does not add or remove any PE components and does not alter your installation architecture, but it does implement some required configuration changes, including certificate extensions for your infrastructure nodes and additional node groups for any compilers and database servers included in your installation.

When you use the guided upgrade process, if conversion is required, PIM notifies you of the requirement and runs the conversion automatically when you confirm that you want to proceed.

When using the CLI, if the configuration of your existing installation is not compatible with PIM, you can run a conversion first, and then run the upgrade with your defined parameters.

Convert your installation

Before you begin

Back up your installation.
Ensure that you have the required access to the PE infrastructure nodes in your installation.
- To convert PE by using PIM on your primary server, you must log in to your primary server as the root user.
- To convert a PE installation that includes remote infrastructure nodes, the machine running PIM must have root SSH access to those nodes. You can configure SSH, or use the -b flag to pass the SSH key or SSH credentials when you run the convert command.

To convert your installation by using PIM:

Download the latest version of PIM.
Go to the Puppet Installation Manager download page and download the binary for your operating system.
Create a JSON file containing the relevant parameters for your PE installation.
For examples illustrating the JSON properties required for different PE architectures, see Creating a conversion parameters file.
Start the conversion.
In your terminal, navigate to the pim directory and run one of the following commands, replacing parameters.json with the actual file name (including the file path, if necessary):
- To run the conversion without debugging and without configuring SSH, use a command like the following example:
```
./pim convert parameters.json
```
- To enable debug logging, add -d or --debug. For example:
```
./pim convert parameters.json --debug
```
- To pass an SSH key or SSH credentials for accessing remote nodes, use the -b flag as shown in the following examples:
```
./pim convert -b user=root -b private-key=~/.ssh/ssh_key parameters.json
```
```
./pim convert -b user=root -b password=ssh_password parameters.json
```

Creating a conversion parameters file

To convert your installation using the Puppet Installation Manager (PIM) command line, you must use a JSON file containing the parameters relevant to your installation architecture and pass that file with the convert command. The JSON file references your installation architecture, including disaster recovery where applicable.

Important: Creating a JSON file containing installation parameters is not required if you use the guided upgrade process. With the guided process, if conversion is required, PIM notifies you of the requirement and runs the conversion automatically when you confirm that you want to proceed.

Configuration examples

The following examples illustrate how to structure the JSON file for converting different PE configurations.

Parameters for converting an extra-large architecture with disaster recovery

{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "replica_host": "pe-xl-core-2.lab1.puppet.vm",
  "replica_postgresql_host": "pe-xl-core-3.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
}

Parameters for converting an extra-large architecture without disaster recovery

{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
}

Parameters for converting a large architecture with disaster recovery

{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "replica_host": "pe-l-core-2.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
}

Parameters for converting a large architecture without disaster recovery

{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
}

Parameters for converting a standard architecture with disaster recovery

{
  "primary_host": "pe-core-0.lab1.puppet.vm",
  "replica_host": "pe-core-2.lab1.puppet.vm",
}

Parameters for converting a standard architecture without disaster recovery

{
  "primary_host": "pe-core-0.lab1.puppet.vm",
}

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.