Upgrade PE using PIM (beta)
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.
- Carefully review Upgrade cautions.
- Check that your modules work with the new PE version. See Test modules before upgrade.
- In Hiera,
pe.conf
, or the console (in the PE Master node group), remove anyagent_version
parameters you set in thepe_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.
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.
- Carefully review Upgrade cautions.
- Check that your modules work with the new PE version. See Test modules before upgrade.
- In Hiera,
pe.conf
, or the console (in the PE Master node group), remove anyagent_version
parameters you set in thepe_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.
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.
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
- 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.
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.
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", }