Upgrade a standalone PE-PostgreSQL installation

To upgrade a large installation with standalone PE-PostgreSQL, run the PE installer first on your PE-PostgreSQL node, then on your primary server, and then upgrade any additional components.

PostgreSQL major version upgrade (14 to 17)

When upgrading to PE 2025.11, the PE-managed PostgreSQL database is upgraded from version 14 to 17.

  • This migration runs automatically as part of the standard upgrade process.

  • No manual steps are required.

Before upgrading:

  • Ensure you have free disk space equal to at least 1.1× the size of your current PE-PostgreSQL data directory. The upgrade process creates a full copy of the database during migration.

  • Plan for additional upgrade time, especially for large databases.

The upgrade displays a warning with the required disk space for your installation, but it does not stop if sufficient space is not available. Verify disk space before starting the upgrade.

Before you begin:

Back up your PE installation.

Ensure you have a valid admin RBAC token in order to upgrade compilers.

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.

  1. Download the tarball for your operating system and architecture. Optionally, you can verify the installation package.
  2. Run tar -xf <TARBALL> to unpack the installation tarball.

    You need about 1 GB of space to untar the installer.

  3. Upgrade your PostgreSQL node.
    1. Ensure that the user_data.conf file on your PostgreSQL node is up to date by running puppet infrastructure recover_configuration on your primary server, and then copying /etc/puppetlabs/enterprise/conf.d to the PostgreSQL node.
    2. Copy the installation tarball to the PostgreSQL node, and from the installer directory, run the installer: sudo ./puppet-enterprise-installer
  4. From the installer directory on your primary server, run sudo ./puppet-enterprise-installer to start the installer, and then follow the CLI instructions to complete your server upgrade.

    To specify a different pe.conf file than the existing file, use the -c flag as shown here:

    sudo ./puppet-enterprise-installer -c <FULL_PATH_TO_pe.conf>

    This flag tells the installer to backup the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a new pe.conf file at /etc/puppetlabs/enterprise/conf.d/pe.conf.

  5. To upgrade compilers, log in to your primary server as root and run one of these commands:
    • To upgrade specific compilers, run: 
      sudo puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
    • To upgrade all compilers simultaneously, run: 
      sudo puppet infrastructure upgrade compiler --all
    • To specify an authentication token location other than the default location, include --token-file <PATH_TO_TOKEN> in the command as shown here: 
      sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
  6. Upgrade the following additional PE infrastructure components:
    • Agents
    • PE client tools: On unmanaged nodes, you must re-install the client tools version that matches the PE version you upgraded to. On managed nodes and infrastructure nodes, client tools are automatically updated when you upgrade PE.
  7. Optional: Remove previous PE packages from all infrastructure nodes. On your primary server, run: puppet infrastructure run remove_old_pe_packages.

    All packages earlier than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER> to the command.

What to do next

Optionally convert legacy compilers to the new style compiler running the PuppetDB service.

Related information