Upgrade PE using the installer tarball

Upgrade PE infrastructure components to get the latest features and fixes. Follow the upgrade instructions for your installation type to ensure you upgrade components in the correct order. Coordinate upgrades to ensure all infrastructure nodes are upgraded in a timely manner, because agent runs and replication fail if infrastructure nodes are running a different agent version than the primary server.

Before you begin

Review the upgrade cautions for major changes to architecture and infrastructure components which might affect your upgrade.

Configure non-production environment for infrastructure nodes

If your infrastructure nodes are in an environment other than production, you must manually configure PE to use your chosen environment before you upgrade.

Important: Only do this procedure if your infrastructure nodes are in an environment that is not production.
In pe.conf, set both of these parameters to the environment your infrastructure nodes are in: 
pe_install::install::classification::pe_node_group_environment
puppet_enterprise::master::recover_configuration::pe_environment

Upgrade a standard installation

To upgrade a standard installation, run the PE installer on your primary server, and then upgrade any additional components.

Before you begin

Back up your PE installation.

If you're upgrading a replica, ensure you have a valid admin RBAC token.

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. 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.
  4. 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.
  5. In disaster recovery installations, upgrade your replica.
    The replica is temporarily unavailable to serve as backup during this step, so time upgrading your replica to minimize risk.
    1. On your primary server logged in as root, run: 
      sudo puppet infrastructure upgrade replica <REPLICA_FQDN>
      If you want to specify an authentication token other than the default, run:
      sudo puppet infrastructure upgrade replica <REPLICA_FQDN> --token-file <PATH_TO_TOKEN>
    2. After the replica upgrade successfully completes, verify that primary and replica services are operational. On your primary server, run: 
      sudo /opt/puppetlabs/bin/puppet-infra status
    3. If your replica reports errors, reinitialize the replica. On your replica, run: 
      sudo /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
  6. 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.

Upgrade a large installation

To upgrade a large installation, run the PE installer on your primary server, and then upgrade compilers and any additional components.

Before you begin

Back up your PE installation.

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

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. 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.
  4. 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>
  5. 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.
  6. In disaster recovery installations, upgrade your replica.
    The replica is temporarily unavailable to serve as backup during this step, so time upgrading your replica to minimize risk.
    1. On your primary server logged in as root, run: 
      sudo puppet infrastructure upgrade replica <REPLICA_FQDN>
      If you want to specify an authentication token other than the default, run:
      sudo puppet infrastructure upgrade replica <REPLICA_FQDN> --token-file <PATH_TO_TOKEN>
    2. After the replica upgrade successfully completes, verify that primary and replica services are operational. On your primary server, run: 
      sudo /opt/puppetlabs/bin/puppet-infra status
    3. If your replica reports errors, reinitialize the replica. On your replica, run: 
      sudo /opt/puppetlabs/bin/puppet-infra reinitialize replica -y
  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.

Upgrade an extra-large installation

You can use the PEADM module to upgrade extra-large installations. Contact your technical account manager for additional support.

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.

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.

Upgrade an unmanaged PostgreSQL installation

You can upgrade a Puppet Enterprise (PE) installation that relies on an unmanaged PostgreSQL database.

Restriction: These steps are for upgrading to PE 2023.7 or later from an earlier 2023.y version, or from PE 2021.7.z. Due to a significant PostgreSQL upgrade in PE 2021.6, if you want to upgrade from 2021.6 or earlier, follow the instructions linked in the Upgrade paths topic to upgrade from 2021.6 or earlier to 2021.7.z before continuing to 2023.y.
  1. Complete setup relevant to your chosen authentication method.
    • Password based authentication: In pe.conf, specify the database password for the pe-hac user as shown in the following example (replacing PASSWORD with the actual password you want to use): 
      "puppet_enterprise::hac_database_password": "PASSWORD"
      Then use your PostgreSQL client to run the following SQL commands (replacing <PASSWORD>):
      CREATE ROLE "pe-hac" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<PASSWORD>';
CREATE ROLE "pe-hac-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<PASSWORD>';
CREATE ROLE "pe-hac-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<PASSWORD>';
CREATE DATABASE "pe-hac" OWNER "pe-hac" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
REVOKE CONNECT ON DATABASE "pe-hac" FROM public;
GRANT CONNECT ON DATABASE "pe-hac" TO "pe-hac-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-hac-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-hac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-hac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-hac-write";
    • Certificate based authentication: Add the following entries to pg_hba.conf, replacing <PRIMARY_CERTNAME> with the certname of your primary server:
      hostssl pe-hac  pe-hac 0.0.0.0/0 cert map=pe-hac-pe-hac-map clientcert=verify-full
hostssl pe-hac  pe-hac-read 0.0.0.0/0 cert map=pe-hac-pe-hac-read-map clientcert=verify-full
hostssl pe-hac  pe-hac-write 0.0.0.0/0 cert map=pe-hac-pe-hac-write-map clientcert=verify-full
      Add the following lines to pg_ident.conf (replacing <PRIMARY_CERTNAME>): 
      pe-hac-pe-hac-map <PRIMARY_CERTNAME> pe-hac
pe-hac-pe-hac-read-map <PRIMARY_CERTNAME> pe-hac-read
pe-hac-pe-hac-write-map <PRIMARY_CERTNAME> pe-hac-write
      Then use your PostgreSQL client to run the following SQL commands:
      CREATE ROLE "pe-hac" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1;
CREATE ROLE "pe-hac-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1;
CREATE ROLE "pe-hac-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1;
CREATE DATABASE "pe-hac" OWNER "pe-hac" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
REVOKE CONNECT ON DATABASE "pe-hac" FROM public;
GRANT CONNECT ON DATABASE "pe-hac" TO "pe-hac-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-hac-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-hac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-hac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-hac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-hac-write";
  2. Download the tarball for your operating system and architecture. Optionally, you can Verify the installation package.
  3. Run tar -xf <TARBALL> to unpack the installation tarball.
    You need about 1 GB of space to untar the installer.
  4. From the installer directory on your primary server, run sudo ./puppet-enterprise-installer -s to start the installer, and then follow the CLI instructions to complete your server upgrade.
    • The -s flag tells the installer to skip database checks.
    • 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>

      The -c flag tells the installer to back up the previous pe.conf file to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and create a 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
CAUTION: Don't use CONCURRENTLY with PostgreSQL 14.0 through 14.3. However, if you do, ensure that you REINDEX without using CONCURRENTLY.