Upgrade an unmanaged PostgreSQL installation

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

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.