Upgrading Puppet Enterprise

Upgrade your PE installation as new versions become available.

Upgrade paths

These are the valid upgrade paths for PE.


If you're on version...	Upgrade to...	Notes
2019.8.z	2019.8.12 (overlap support) or 2021.7.z (LTS)	Important: 2019.8.z is in overlap support until EOL in February 2023. You can upgrade to the new LTS (2021.7.z) from any 2019.8.z version. For important information about this upgrade, refer to Upgrading Puppet Enterprise in the 2021.7.z documentation.
2019.y	2019.8.z
2018.1.2 or later 2018.1.3 or later with disaster recovery	2019.8.z	You must have version 2018.1.2 or later in order to complete prerequisites for upgrade to the latest version. With disaster recovery enabled, you must have version 2018.1.3 in order to upgrade to the latest version. Alternatively, you can forget and then recreate your replica after upgrade.
2018.1.0 or 2018.1.1	2018.1.z
2017.3.z	2018.1.z
2017.2.z
2017.1.z
2016.5.z
2016.4.10 or later
2016.4.9 or earlier	2016.4.z, then 2018.1	To upgrade to 2018.1 from 2015.2.z through 2016.4.9, you must first upgrade to the latest 2016.4.z.
2016.2.z
2016.1.z
2015.3.z
2015.2.z
3.8.x	2016.4.z, then 2018.1	To upgrade from 3.8.x, you must first migrate to the latest 2016.4.z. This upgrade requires a different process than upgrades from other versions.

Upgrade cautions

These are the major changes to PE since the last long-term support release, 2018.1. Review these recommendations and plan accordingly before upgrading to this version.

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

Retired primary server platforms in 2019.8

Support for Enterprise Linux 6 and Ubuntu 16.04 as a primary server platform was removed in 2019.8. If your primary server is installed on one of these platforms, you must update the operating system before you can upgrade to this version of PE.

Follow these steps to upgrade from an unsupported primary server platform.

Configure a new node with a supported primary server platform, for example Enterprise Linux 7 or 8, or Ubuntu 18.04.
Install your current PE version on the new node.
Back up your existing installation.
Restore your installation on the new primary server using the backup you created.
Upgrade to the latest PE version.
If you have compilers, reprovision them.
If you have a replica, forget and then reprovision it.

PuppetDB migrations in PE 2019.1, 2019.3, and 2019.7

Deleting PuppetDB reports and truncating the resource events table before you upgrade can reduce migration time and lessen downtime, especially when the upgrade involves a significant database migration.

CAUTION: If you have a replica, you must stop PuppetDB from syncing the deleted reports back while you are deleting the reports. Therefore, it is crucial that you delete reports on your primary server and replica at the same time. Make sure the report deletion process is complete on both, and then restart the PuppetDB service on your primary server and replica.

On your primary server (and replica), stop the PuppetDB service by running:
```
puppet resource service pe-puppetdb ensure=stopped
```
Remember: If you have a replica, you must do these steps on the primary server and replica at the same time.

The next step depends on the Puppet Enterprise (PE) version you're upgrading from. Regardless of the version, if you have a replica, you must perform these steps on the primary server and replica at the same time.

If you're upgrading from PE 2019.7 or later: Run the packaged delete-reports command on your primary server (and replica):
```
/opt/puppetlabs/bin/puppetdb delete-reports
```

If you're upgrading from a PE version earlier than 2019.7:

On your PE-PostgreSQL server, create a file named /tmp/delete-reports.sql and set it to be owned by the pe-postgres user (chown pe-postgres:pe-postgres /tmp/delete-reports.sql). Then,

Add contents to the .sql file according to your PE version.

For PE versions 2019.3 through 2019.6, insert the following content:

BEGIN TRANSACTION;
                        
                        ALTER TABLE certnames DROP CONSTRAINT IF EXISTS certnames_reports_id_fkey;
                        UPDATE certnames SET latest_report_id = NULL;
                        
                        DO $$ DECLARE
                        r RECORD;
                        BEGIN
                        FOR r IN (SELECT tablename FROM pg_tables WHERE tablename LIKE 'resource_events_%') LOOP
                        EXECUTE 'DROP TABLE ' || quote_ident(r.tablename);
                        END LOOP;
                        END $$;
                        
                        TRUNCATE TABLE reports CASCADE;
                        
                        ALTER TABLE certnames
                        ADD CONSTRAINT certnames_reports_id_fkey
                        FOREIGN KEY (latest_report_id) REFERENCES reports(id) ON DELETE SET NULL;
                        
                        COMMIT TRANSACTION;

For PE versions earlier than 2019.3, insert the following content:

BEGIN TRANSACTION;
                            
                            ALTER TABLE certnames DROP CONSTRAINT IF EXISTS certnames_reports_id_fkey;
                            UPDATE certnames SET latest_report_id = NULL;
                            TRUNCATE TABLE reports CASCADE;
                            
                            ALTER TABLE certnames
                            ADD CONSTRAINT certnames_reports_id_fkey
                            FOREIGN KEY (latest_report_id) REFERENCES reports(id) ON DELETE SET NULL;
                            
                            COMMIT TRANSACTION;

Run this command on your primary server (and replica):

su - pe-postgres -s /bin/bash -c "/opt/puppetlabs/server/bin/psql -d pe-puppetdb -f /tmp/delete-reports.sql"

Wait for the deletion process to finish.
Restart the PuppetDB service on your primary server (and replica) by running:
```
puppet resource service pe-puppetdb ensure=running
```

Java 11 upgrade in PE 2019.3

PE 2019.3 includes an upgrade from Java version 8 to version 11. If you've customized PE Java services, or use plug-ins that include Java code, test PE 2019.3 and later thoroughly in a non-production environment before upgrading.

Retired split installations in PE 2019.2

Split installations, where the primary server, console, and PuppetDB are installed on separate nodes, are no longer supported.

Before upgrading to 2019.2 or later, you must migrate from a split to a standard installation. For instructions, see Migrate from a split to a standard installation in the documentation for your current version.

Orchestrator memory use increase in PE 2019.2

Puppet orchestrator uses more memory in version 2019.2 than in previous versions due to the addition of a Java virtual machine (JVM), which enables new features and functionalities such as plans. If your memory use is near capacity when running PE 2019.1 or older versions, allocate additional memory before upgrading to PE 2019.2.

Additionally, take care when writing plans, as they can require more memory than is allocated to the orchestrator. To work around this issue, rewrite the plan or increase the memory allocated to the orchestrator.

PostgreSQL 11 upgrade in PE 2019.2

PE 2019.2.0 includes an upgrade from pe-postgresql version 9.6 to version 11. This upgrade involves a datastore migration that requires extra disk space (110% of the current 9.6 datastore) and extra time to upgrade (roughly two and four minutes of additional time per 10GB of datastore size). The installer issues a warning and cancels the upgrade if there is insufficient space.

To review the size of your PostgreSQL installation as well as the size and number of available bytes for the partition, run facter -p pe_postgresql_info on the node that runs the pe-postgresql service.

To speed the migration and optimize queries, clean up the PE-PosgreSQL database prior to upgrade by applying the pe_databases module to nodes running the pe-postgresql service. For best results, apply the module at least one week prior to upgrade to allow the module's maintenance schedule enough time to clean all databases.

After upgrading, you can optionally remove packages and directories associated with older PostgreSQL versions with the command puppet infrastructure run remove_old_postgresql_versions. If applicable, the installer prompts you to complete this cleanup.

Note: If you use an external PostgreSQL instance not managed by PE, you must separately upgrade the instance to PostgreSQL 11. For more information, see Upgrading PostgreSQL.

TLSv1 and v1.1 disabled in PE 2019.1

As of PE 2019.1, TLSv1 and TLSv1.1 is now disabled by default to comply with security regulations. You must enable TLSv1 to upgrade agents on these platforms:

AIX
CentOS 5
RHEL 5
SLES 11
Solaris 10, 11
Windows Server 2008 R2

Certificate architecture and handling in PE 2019.0

PE 2019.0 and later, courtesy of Puppet Server, uses an intermediate certificate authority architecture by default. When you upgrade to PE 2019.0 or later, you have several options for whether and when to adopt the new intermediate certificate architecture:

To upgrade to 2019.0 or later and keep your existing CA, upgrade infrastructure nodes and agents as normal. You can continue to use pre-6.x agents with a Puppet 6.x or PE 2019.0 or later primary server as long as you don't regenerate certificates.
To migrate to 2019.0 or later and keep your existing CA, install the new version and copy /etc/puppetlabs/puppet/ssl from your old primary server. You can continue to use pre-6.x agents with a Puppet 6.x or PE 2019.0 or later primary server as long as you don't regenerate certificates.
To adopt the new CA architecture, upgrade both your primary server and agents, and then regenerate certificates. If you don't upgrade all of your nodes to 6.x, don't regenerate certificates, because pre-6.x agents won't work with the new CA architecture.

MCollective removal in PE 2019.0

If you're upgrading from a 2018.1 installation with MCollective enabled, you must take additional steps to ensure a successful upgrade. If any nodes are configured with MCollective or ActiveMQ profiles when you attempt to upgrade, the installer halts and prompts you to remove the profiles.

Before upgrading to 2019.x

Remove MCollective from nodes in your infrastructure:
1. In the console, click Node groups, and select the node group PE Infrastructure.
2. On the Configuration tab, in the puppet_enterprise class, set the mcollective parameter to absent.
3. Click Add parameter and commit the change, then run Puppet on infrastructure nodes.
After completing these steps, the server components of MCollective, including pe-activemq and the peadmin user, are removed from the primary server and the MCollective service on agents is stopped. You must complete the upgrade to 2019.0 or later to completely remove MCollective from agents.
Remove any of these deprecated parameters:
- mcollective_middleware_hosts
- mcollective
- mcollective_middleware_port
- mcollective_middleware_user
- mcollective_middleware_password
Tip: If your PuppetDB includes outdated catalogs for nodes that aren't currently being managed, the installer might report that MCollective is active on those nodes. You can deactivate the nodes with puppet node deactivate or use Puppet to update the records.

After upgrading to 2019.x

Manually remove these node groups:
- PE MCollective
- PE ActiveMQ Broker
- Any custom node group you created for ActiveMQ hubs
If you customized classification with references to MCollective or ActiveMQ profiles, remove the profiles from your classification. In this version of PE, nodes that include MCollective or ActiveMQ profiles trigger a warning during agent runs. Future versions of PE that remove the profiles completely can trigger failures in catalog compilation if you leave the profiles in place.

Test modules before upgrade

To ensure that your modules work with the newest version of PE, update and test them with Puppet Development Kit (PDK) before upgrading.

Before you begin

If you are already using PDK, your modules should pass validation and unit tests with your currently installed version of PDK.

Update PDK with each new release to ensure compatibility with new versions of PE.

Download and install PDK. If you already have PDK installed, this updates PDK to its latest version. For detailed instructions and download links, see the installing instructions.
If you have not previously used PDK with your modules, convert them to a PDK compatible format. This makes changes to your module to enable validation and unit testing with PDK. For important usage details, see the converting modules documentation.
For example, from within the module directory, run:
```
pdk convert
```
If your modules are already compatible with PDK, update them to the latest module template. If you converted modules in step 2, you do not need to update the template. To learn more about updating, see the updating module templates documentation.
For example, from within the module directory, run:
```
pdk update
```
Validate and run unit tests for each module, specifying the version of PE you are upgrading to. When specifying a PE version, be sure to specify at least the year and the release number, such as 2018.1. For information about module validations and testing, see the validating and testing modules documentation.
For example, from within the module directory, run:
```
pdk validate
pdk test unit
```
The pdk test unit command verifies that testing dependencies and directories are present and runs the unit tests that you write. It does not create unit tests for your module.
If your module fails validation or unit tests, make any necessary changes to your code.

Results

After you've verified that your modules work with the new PE version, you can continue with your upgrade.

Upgrade PE

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 on infrastructure nodes 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: You only need to follow these steps 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
Run puppet-enterprise-installer -- --pe-environment <env>

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. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

Remove from the console (in the PE Master node group), Hiera, or pe.conf any agent_version parameters that you've set in the pe_repo class that matches your infrastructure nodes. Doing so ensures that upgrade isn't blocked by attempting to download a non-default agent version for your infrastructure OS and architecture.

If you're upgrading from a version earlier than 2019.7, the upgrade process includes a significant PuppetDB migration. You can expedite this process by deleting report from PuppetDB before upgrading. For instructions, refer to PuppetDB migrations in PE 2019.1, 2019.3, and 2019.7.
Download the tarball appropriate to your operating system and architecture.
Unpack the installation tarball: tar -xf <tarball>
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
```
sudo ./puppet-enterprise-installer
```
- If you want to specify a different pe.conf file other than the existing file, use the -c flag: sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
  With this flag, your previous pe.conf is backed up to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and a new pe.conf is created at /etc/puppetlabs/enterprise/conf.d/pe.conf.
Upgrade these additional PE infrastructure components.
- Agents
- PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.
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>
  To specify the location of an authentication token other than the default: 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
Optional: Remove old PE packages from all infrastructure nodes by running, from your primary server: puppet infrastructure run remove_old_pe_packages
All packages older than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER>

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. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

If you're upgrading from a version earlier than 2019.7, the upgrade process includes a significant PuppetDB migration. You can expedite this process by deleting report from PuppetDB before upgrading. For instructions, refer to PuppetDB migrations in PE 2019.1, 2019.3, and 2019.7.
Download the tarball appropriate to your operating system and architecture.
Unpack the installation tarball: tar -xf <tarball>
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
```
sudo ./puppet-enterprise-installer
```
- If you want to specify a different pe.conf file other than the existing file, use the -c flag: sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
  With this flag, your previous pe.conf is backed up to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and a new pe.conf is created at /etc/puppetlabs/enterprise/conf.d/pe.conf.
To upgrade compilers, on your primary server logged in as root, run: puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
- To upgrade all compilers simultaneously: sudo puppet infrastructure upgrade compiler --all
- To specify the location of an authentication token other than the default: sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
Upgrade these additional PE infrastructure components.
- Agents
- PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.
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>
  To specify the location of an authentication token other than the default: 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
Optional: Remove old PE packages from all infrastructure nodes by running, from your primary server: puppet infrastructure run remove_old_pe_packages
All packages older than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER>

What to do next

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

Upgrade an extra-large installation

For help upgrading an extra-large installation, reach out to your technical account manager.

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. If you're upgrading from 2018.1, the RBAC token must be generated by a user with Job orchestrator and Node group view permissions.

If you're upgrading from a version earlier than 2019.7, the upgrade process includes a significant PuppetDB migration. You can expedite this process by deleting report from PuppetDB before upgrading. For instructions, refer to PuppetDB migrations in PE 2019.1, 2019.3, and 2019.7.
Download the tarball appropriate to your operating system and architecture.
Unpack the installation tarball: tar -xf <tarball>
You need about 1 GB of space to untar the installer.
Upgrade your PostgreSQL node.
1. Ensure that the pe.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
From the installer directory on your primary server, run the installer and follow the CLI instructions to complete your server upgrade:
```
sudo ./puppet-enterprise-installer
```
- If you want to specify a different pe.conf file other than the existing file, use the -c flag: sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>
  With this flag, your previous pe.conf is backed up to /etc/puppetlabs/enterprise/conf.d/<TIMESTAMP>.conf and a new pe.conf is created at /etc/puppetlabs/enterprise/conf.d/pe.conf.
To upgrade compilers, on your primary server logged in as root, run: puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
- To upgrade all compilers simultaneously: sudo puppet infrastructure upgrade compiler --all
- To specify the location of an authentication token other than the default: sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
Upgrade these additional PE infrastructure components.
- Agents
- PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.
Optional: Remove old PE packages from all infrastructure nodes by running, from your primary server: puppet infrastructure run remove_old_pe_packages
All packages older than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER>

What to do next

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

Upgrade an unmanaged PostgreSQL installation

To upgrade a PE installation that relies on an unmanaged PostgreSQL database, you must first upgrade PostgreSQL to version 11, if necessary. Then, prepare your Puppet Enterprise (PE) databases and pe.conf file, and finally upgrade PE. Upgrade steps vary slightly depending on whether you use password or SSL authentication.

Before you begin

Back up your PE installation.

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

Important: These steps use the default file and directory locations, and these steps assume the PostgreSQL superuser is postgres. Change these to match your installation as needed.

If you are upgrading from a PE version earlier than 2019.2.0, upgrade PostgreSQL.
1. On your PostgreSQL node, install these packages:
  - postgresql11
  - postgresql11-libs
  - postgresql11-contrib
  - postgresql11-server
2. Stop the PostgreSQL 9.6 service:
```
systemctl stop postgresql-9.6.service
```
3. As the PostgreSQL user, create a new database:
```
su - postgres
/usr/pgsql-11/bin/pg_ctl -D /var/lib/pgsql/11/data/ initdb
```
4. If you use certificate authentication, take note of the location of your certificate, private key, and certificate authority files. You may need to move them to the new install directory, and you may need to update postgresql.conf.
5. Copy your postgresql.conf file from /var/lib/pgsql/9.6/data/ to /var/lib/pgsql/11/data/ and update the data directory setting. If you moved the certificate, private key, and certificate authority files, update the ssl_cert_file, ssl_key_file, and ssl_ca_file settings.
6. Migrate databases to PostgreSQL 11:
```
 /usr/pgsql-11/bin/pg_upgrade -b /usr/pgsql-9.6/bin -B /usr/pgsql-11/bin/ -d  /var/lib/pgsql/9.6/data -D /var/lib/pgsql/11/data/
```
7. Copy your pg_hba.conf and pg_ident.conf files from /var/lib/pgsql/9.6/data/ to /var/lib/pgsql/11/data/.

If necessary, update pg_hba.conf to ensure all relevant PE database roles have access.

This is an example of how this would look when using certificate authentication:

hostssl pe-activity pe-activity 0.0.0.0/0 cert map=pe-activity-pe-activity-map clientcert=1
hostssl pe-activity pe-activity-read 0.0.0.0/0 cert map=pe-activity-pe-activity-read-map clientcert=1
hostssl pe-activity pe-activity-write 0.0.0.0/0 cert map=pe-activity-pe-activity-write-map clientcert=1
hostssl pe-classifier pe-classifier 0.0.0.0/0 cert map=pe-classifier-pe-classifier-map clientcert=1
hostssl pe-classifier pe-classifier-read 0.0.0.0/0 cert map=pe-classifier-pe-classifier-read-map clientcert=1
hostssl pe-classifier pe-classifier-write 0.0.0.0/0 cert map=pe-classifier-pe-classifier-write-map clientcert=1
hostssl pe-inventory pe-inventory 0.0.0.0/0 cert map=pe-inventory-pe-inventory-map clientcert=1
hostssl pe-inventory pe-inventory-read 0.0.0.0/0 cert map=pe-inventory-pe-inventory-read-map clientcert=1
hostssl pe-inventory pe-inventory-write 0.0.0.0/0 cert map=pe-inventory-pe-inventory-write-map clientcert=1
hostssl pe-orchestrator pe-orchestrator 0.0.0.0/0 cert map=pe-orchestrator-pe-orchestrator-map clientcert=1
hostssl pe-orchestrator pe-orchestrator-read 0.0.0.0/0 cert map=pe-orchestrator-pe-orchestrator-read-map clientcert=1
hostssl pe-orchestrator pe-orchestrator-write 0.0.0.0/0 cert map=pe-orchestrator-pe-orchestrator-write-map clientcert=1
hostssl pe-puppetdb pe-puppetdb 0.0.0.0/0 cert map=pe-puppetdb-pe-puppetdb-map clientcert=1
hostssl pe-puppetdb pe-puppetdb-migrator 0.0.0.0/0 cert map=pe-puppetdb-pe-puppetdb-migrator-map clientcert=1
hostssl pe-puppetdb pe-puppetdb-read 0.0.0.0/0 cert map=pe-puppetdb-pe-puppetdb-read-map clientcert=1
hostssl pe-rbac pe-rbac 0.0.0.0/0 cert map=pe-rbac-pe-rbac-map clientcert=1
hostssl pe-rbac pe-rbac-read 0.0.0.0/0 cert map=pe-rbac-pe-rbac-read-map clientcert=1
hostssl pe-rbac pe-rbac-write 0.0.0.0/0 cert map=pe-rbac-pe-rbac-write-map clientcert=1
local all postgres peer

If necessary, and you are using certificate authentication, update pg_ident.conf to ensure all relevant PE database roles are mapped appropriately.

For example:

pe-activity-pe-activity-map <PRIMARY_CERTNAME> pe-activity
pe-activity-pe-activity-read-map <PRIMARY_CERTNAME> pe-activity-read
pe-activity-pe-activity-write-map <PRIMARY_CERTNAME> pe-activity-write
pe-classifier-pe-classifier-map <PRIMARY_CERTNAME> pe-classifier
pe-classifier-pe-classifier-read-map <PRIMARY_CERTNAME> pe-classifier-read
pe-classifier-pe-classifier-write-map <PRIMARY_CERTNAME> pe-classifier-write
pe-inventory-pe-inventory-map <PRIMARY_CERTNAME> pe-inventory
pe-inventory-pe-inventory-read-map <PRIMARY_CERTNAME> pe-inventory-read
pe-inventory-pe-inventory-write-map <PRIMARY_CERTNAME> pe-inventory-write
pe-orchestrator-pe-orchestrator-map <PRIMARY_CERTNAME> pe-orchestrator
pe-orchestrator-pe-orchestrator-read-map <PRIMARY_CERTNAME> pe-orchestrator-read
pe-orchestrator-pe-orchestrator-write-map <PRIMARY_CERTNAME> pe-orchestrator-write
pe-puppetdb-pe-puppetdb-map <PRIMARY_CERTNAME> pe-puppetdb
pe-puppetdb-pe-puppetdb-migrator-map <PRIMARY_CERTNAME> pe-puppetdb-migrator
pe-puppetdb-pe-puppetdb-read-map <PRIMARY_CERTNAME> pe-puppetdb-read
pe-rbac-pe-rbac-map <PRIMARY_CERTNAME> pe-rbac
pe-rbac-pe-rbac-read-map <PRIMARY_CERTNAME> pe-rbac-read
pe-rbac-pe-rbac-write-map <PRIMARY_CERTNAME> pe-rbac-write

Start or restart the PostgreSQL 11 service. If you migrated to 11, start the PostgreSQL 11 service for the first time. If you were already on 11 and you made changes to the conf files, restart the PostgreSQL 11 service.
```
systemctl start postgresql-11
```

Prepare PE databases for upgrade.

As the PostgreSQL user, clean up the database:
```
su - postgres
/usr/pgsql-11/bin/vacuumdb --analyze --all
```

If you are upgrading from 2018.1 or 2019.0, create a directory for the pe-inventory tablespace. Depending on the version you are upgrading from, this step may not be necessary.

First, run:

mkdir -p <PATH TO TABLESPACES DIR>/pe-inventory
chown postgres:postgres <PATH TO TABLESPACES DIR>/pe-inventory
chmod 700 <PATH TO TABLESPACES DIR>/pe-inventory

Then, create the database by running the following commands at the psql prompt:

CREATE TABLESPACE "pe-inventory" LOCATION '<path to tablespaces dir>/pe-inventory";
CREATE DATABASE "pe-inventory" OWNER "postgres" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0 TABLESPACE 'pe-inventory';
REVOKE CONNECT ON DATABASE "pe-inventory" FROM public;

Create any new or missing roles as necessary.

These commands include all roles. You may not need to create the base roles; however, if you are upgrading from 2018.1, you need to create the pe-puppetdb-migrator role as well as all -read and -write roles.

Note: The follow commands include passwords for the roles. You can omit passwords if you are using certificate authentication.

CREATE ROLE "pe-inventory" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<INVENTORY_DATABASE_PASSWORD>';
CREATE ROLE "pe-inventory-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<INVENTORY_DATABASE_PASSWORD>';
CREATE ROLE "pe-inventory-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<INVENTORY_DATABASE_PASSWORD>';
CREATE ROLE "pe-puppetdb-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<PUPPETDB_PASSWORD>';
CREATE ROLE "pe-puppetdb-migrator" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<PUPPETDB_PASSWORD>';
CREATE ROLE "pe-puppetdb" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<PUPPETDB_PASSWORD>';
CREATE ROLE "pe-classifier" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<CLASSIFIER_DATABASE_PASSWORD>';
CREATE ROLE "pe-classifier-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<CLASSIFIER_DATABASE_PASSWORD>';
CREATE ROLE "pe-classifier-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<CLASSIFIER_DATABASE_PASSWORD>';
CREATE ROLE "pe-rbac" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<RBAC_DATABASE_PASSWORD>';
CREATE ROLE "pe-rbac-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<RBAC_DATABASE_PASSWORD>';
CREATE ROLE "pe-rbac-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<RBAC_DATABASE_PASSWORD>';
CREATE ROLE "pe-activity" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<ACTIVITY_DATABASE_PASSWORD>';
CREATE ROLE "pe-activity-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<ACTIVITY_DATABASE_PASSWORD>';
CREATE ROLE "pe-activity-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<ACTIVITY_DATABASE_PASSWORD>';
CREATE ROLE "pe-orchestrator" LOGIN NOCREATEROLE NOCREATEDB SUPERUSER CONNECTION LIMIT -1 PASSWORD '<ORCHESTRATOR_DATABASE_PASSWORD>';
CREATE ROLE "pe-orchestrator-read" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<ORCHESTRATOR_DATABASE_PASSWORD>';
CREATE ROLE "pe-orchestrator-write" LOGIN NOCREATEROLE NOCREATEDB NOSUPERUSER CONNECTION LIMIT -1 PASSWORD '<ORCHESTRATOR_DATABASE_PASSWORD>';

Update database extensions and role permissions:

\c "pe-puppetdb"
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
ALTER EXTENSION "pgcrypto" UPDATE;
CREATE EXTENSION IF NOT EXISTS "pg_trgm";
ALTER EXTENSION "pg_trgm" UPDATE;
GRANT CONNECT ON DATABASE "pe-puppetdb" TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT EXECUTE ON FUNCTIONS TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT USAGE ON SEQUENCES TO "pe-puppetdb-read";
GRANT SELECT ON ALL TABLES IN SCHEMA "public" TO "pe-puppetdb-read";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA "public" TO "pe-puppetdb-read";
GRANT "pe-puppetdb" TO "pe-puppetdb-migrator";
REVOKE CONNECT ON DATABASE "pe-puppetdb" FROM "pe-puppetdb";
GRANT CONNECT ON DATABASE "pe-puppetdb" TO "pe-puppetdb-migrator" WITH GRANT OPTION;
SET ROLE "pe-puppetdb-migrator"; GRANT CONNECT ON DATABASE "pe-puppetdb" TO "pe-puppetdb"; SET ROLE "postgres";
GRANT CONNECT ON DATABASE "pe-puppetdb" TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT EXECUTE ON FUNCTIONS TO "pe-puppetdb-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-puppetdb" IN SCHEMA "public" GRANT USAGE ON SEQUENCES TO "pe-puppetdb-read";
GRANT SELECT ON ALL TABLES IN SCHEMA "public" to "pe-puppetdb-read";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA "public" TO "pe-puppetdb-read";
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "public" TO "pe-puppetdb-read";

\c "pe-rbac"
CREATE EXTENSION IF NOT EXISTS "citext";
ALTER EXTENSION "citext" UPDATE;
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
ALTER EXTENSION "pgcrypto" UPDATE;
GRANT CONNECT ON DATABASE "pe-rbac" TO "pe-rbac-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-rbac" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-rbac-read";
GRANT CONNECT ON DATABASE "pe-rbac" TO "pe-rbac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-rbac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-rbac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-rbac" in SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-rbac-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-rbac" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-rbac-write";

\c "pe-inventory"
REVOKE CREATE ON SCHEMA public FROM public;
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
ALTER EXTENSION "pgcrypto" UPDATE;
GRANT CONNECT ON DATABASE "pe-inventory" TO "pe-inventory-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-inventory" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-inventory-read";
GRANT CONNECT ON DATABASE "pe-inventory" TO "pe-inventory-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-inventory" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-inventory-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-inventory" IN SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-inventory-write";

\c "pe-orchestrator"
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
ALTER EXTENSION "pgcrypto" UPDATE;
GRANT CONNECT ON DATABASE "pe-orchestrator" TO "pe-orchestrator-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-orchestrator" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-orchestrator-read";
GRANT CONNECT ON DATABASE "pe-orchestrator" TO "pe-orchestrator-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-orchestrator" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-orchestrator-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-orchestrator" in SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-orchestrator-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-orchestrator" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-orchestrator-write";

\c "pe-activity"
GRANT CONNECT ON DATABASE "pe-activity" TO "pe-activity-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-activity" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-activity-read";
GRANT CONNECT ON DATABASE "pe-activity" TO "pe-activity-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-activity" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-activity-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-activity" in SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-activity-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-activity" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-activity-write";


\c "pe-classifier"
GRANT CONNECT ON DATABASE "pe-classifier" TO "pe-classifier-read";
ALTER DEFAULT PRIVILEGES FOR USER "pe-classifier" IN SCHEMA "public" GRANT SELECT ON TABLES TO "pe-classifier-read";
GRANT CONNECT ON DATABASE "pe-classifier" TO "pe-classifier-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-classifier" IN SCHEMA "public" GRANT ALL PRIVILEGES ON TABLES TO "pe-classifier-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-classifier" in SCHEMA "public" GRANT ALL PRIVILEGES ON SEQUENCES TO "pe-classifier-write";
ALTER DEFAULT PRIVILEGES FOR USER "pe-classifier" IN SCHEMA "public" GRANT ALL PRIVILEGES ON FUNCTIONS TO "pe-classifier-write";

Prepare your pe.conf file for upgrade.

Password authentication

Add your inventory database password and verify existing host, port, and password parameters.

"puppet_enterprise::puppet_master_host": "<PRIMARY_CERTNAME>"
"puppet_enterprise::database_host": "<DATABASE_NODE_CERTNAME>"
"puppet_enterprise::database_port": 5432
"puppet_enterprise::puppetdb_database_password": "<PUPPETDB_PASSWORD>"
"puppet_enterprise::classifier_database_password": "<CLASSIFIER_DATABASE_PASSWORD>"
"puppet_enterprise::activity_database_password": "<ACTIVITY_DATABASE_PASSWORD>"
"puppet_enterprise::rbac_database_password": "<RBAC_DATABASE_PASSWORD>"
"puppet_enterprise::orchestrator_database_password": "<ORCHESTRATOR_DATABASE_PASSWORD>"
"puppet_enterprise::inventory_database_password": "<INVENTORY_DATABASE_PASSWORD>"

Certificate authentication

Verify existing port and SSL parameters, and remove any password parameters.

"puppet_enterprise::database_ssl": true
"puppet_enterprise::database_cert_auth": true
"puppet_enterprise::database_port": 5432
"puppet_enterprise::profile::console::database_properties": "?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=/etc/puppetlabs/puppet/ssl/certs/ca.pem&sslkey=/opt/puppetlabs/server/data/console-services/certs/<PRIMARY_CERTNAME>.private_key.pk8&sslcert=/opt/puppetlabs/server/data/console-services/certs/<PRIMARY_CERTNAME>.cert.pem"
"puppet_enterprise::profile::puppetdb::database_properties": "?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=/etc/puppetlabs/puppet/ssl/certs/ca.pem&sslkey=/etc/puppetlabs/puppetdb/ssl/<PRIMARY_CERTNAME>.private_key.pk8&sslcert=/etc/puppetlabs/puppetdb/ssl/<PRIMARY_CERTNAME>.cert.pem"
"puppet_enterprise::profile::orchestrator::database_properties": "?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=/etc/puppetlabs/puppet/ssl/certs/ca.pem&sslkey=/etc/puppetlabs/orchestration-services/ssl/<PRIMARY_CERTNAME>.private_key.pk8&sslcert=/etc/puppetlabs/orchestration-services/ssl/<PRIMARY_CERTNAME>.cert.pem"

If you're upgrading from a version earlier than 2019.7, the upgrade process includes a significant PuppetDB migration. You can expedite this process by deleting report from PuppetDB before upgrading. For instructions, refer to PuppetDB migrations in PE 2019.1, 2019.3, and 2019.7.
Download the tarball appropriate to your operating system and architecture.
Unpack the installation tarball: tar -xf <tarball>
You need about 1 GB of space to untar the installer.
From the installer directory on your primary server, run the installer, using the -c flag to specify your existing pe.conf file and the -s flag to skip database checks by the installer. Follow the CLI instructions to complete your server upgrade.
```
sudo ./puppet-enterprise-installer -s -c <FULL PATH TO pe.conf>
```
To upgrade compilers, on your primary server logged in as root, run: puppet infrastructure upgrade compiler <COMPILER_FQDN-1>,<COMPILER_FQDN-2>
- To upgrade all compilers simultaneously: sudo puppet infrastructure upgrade compiler --all
- To specify the location of an authentication token other than the default: sudo puppet infrastructure upgrade compiler <COMPILER_FQDN> --token-file <PATH_TO_TOKEN>
Upgrade these additional PE infrastructure components.
- Agents
- PE client tools — On unmanaged nodes only, re-install the version of client tools that matches the PE version you upgraded to. Client tools are automatically updated on infrastructure nodes and managed nodes when you upgrade PE.
Optional: Remove old PE packages from all infrastructure nodes by running, from your primary server: puppet infrastructure run remove_old_pe_packages
All packages older than the current version are removed by default. To remove specific versions, append pe_version=<VERSION_NUMBER>

What to do next

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

Migrate PE

As an alternative to upgrading, you can migrate your PE installation. Migrating results in little or no downtime, but it requires additional system resources because you must configure a new primary server.

Note: This procedure is not supported for installations with disaster recovery.

Migrate a standard installation

Migrate a standard installation by standing up a new primary server, restoring it with your existing installation, upgrading it, and then pointing agents at the new primary.

Before you begin

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

Install your current PE version on a new primary server node.
Back up your existing installation.
Restore your installation on the new primary server using the backup you created.
Upgrade your new primary server to the latest PE version.
Update nodes' puppet.conf server setting to the hostname for your new primary server:
```
sudo puppet config set server <PRIMARY_HOSTNAME>
```

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.