Upgrade PE: split installation

When you upgrade a split (and LEI) installation, the main components of PE (the Puppet master, PuppetDB, the PE console, and any compile masters/hubs and spokes) are upgraded on the different nodes they are installed on.

The PE installer is idempotent, meaning that you can run it as many times as needed without affecting the outcome. If you encounter errors during installation, you can fix them and run the installer again.

The upgrade process for a split installation consists of the following high-level steps:

Upgrade your Puppet master, PuppetDB, and PE console nodes.

Upgrade your remaining infrastructure and LEI nodes

Upgrade your Puppet agents.

Before you begin: If your master is set to noop mode (noop = true in puppet.conf on the master), remove or comment out this flag prior to upgrade. The installer fails if you attempt to upgrade in noop mode.

Upgrade the Puppet master server

When you upgrade a split installation, you first upgrade the Puppet master.

Download and unpack the PE installation/upgrade tarball. (Run tar -xf <tarball>. Note that you need about 1 GB of space in /tmp to untar the installer.)

Stop the Puppet agent service with sudo puppet resource service puppet ensure=stopped.

From the installer directory, run the installer/upgrader. The steps will vary depending on the path you choose.

To use a pe.conf file that already exists run the upgrade with the -c flag pointed at the pe.conf file.

sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

With this option, 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.

Warning: If you’re using a pre-populated file, be sure you’ve set the parameters correctly as detailed in the following steps.

To have the installer/upgrade open a copy of pe.conf for you to edit and upgrade with, run the installer without the -c flag.

sudo ./puppet-enterprise-installer

Set the following parameters in pe.conf:

Important: Do not use single quotes on parameter values. Use double quotes as shown in the examples.

Note: In the following examples, <FQDN> is the fully qualified domain name of the server. For example, the parameter and value should be expressed as "puppet_enterprise::puppet_master_host": "master.example.com".

Parameter

Value

"console_admin_password":

"<PASSWORD>"— Replace <PASSWORD> with your password used to log into the PE console.

"puppet_enterprise::puppet_master_host":

"<FQDN>"— Provide the<FQDN> of the node hosting the Puppet master.

"puppet_enterprise::console_host":

"<FQDN>"— Provide the<FQDN> of the node hosting the PE console.

"puppet_enterprise::puppetdb_host":

"<FQDN>"— Provide the<FQDN> of the node hosting PuppetDB.

If you’re upgrading an installation that uses an external PostgreSQL instance, set the following parameters in pe.conf:

Important: If needed, substitute the database user names if you’ve replaced the defaults, which are shown in this step.

Parameter

Value

"puppet_enterprise::activity_service_regular_db_user":

"pe-activity"

"puppet_enterprise::activity_service_migration_db_user":

"pe-activity"

"puppet_enterprise::classifier_service_regular_db_user":

"pe-classifier"

"puppet_enterprise::classifier_service_migration_db_user":

"pe-classifier"

"puppet_enterprise::orchestrator_service_regular_db_user":

"pe-orchestrator"

"puppet_enterprise::orchestrator_service_migration_db_user":

"pe-orchestrator"

"puppet_enterprise::rbac_service_regular_db_user":

"pe-rbac"

"puppet_enterprise::rbac_service_migration_db_user":

"pe-rbac"

Save and close the file.

This starts the upgrade on the Puppet master server.

Upgrade the PuppetDB server

In a split installation, after you upgrade the Puppet master, you’re ready to upgrade your PuppetDB server.

Transfer the PE installation/upgrade tarball and the /etc/puppetlabs/enterprise/conf.d/ directory to the PuppetDB node.

Unpack the PE installation/upgrade tarball. (Run tar -xf <tarball>. Note that you need about 1 GB of space in /tmp to untar the installer.)

Stop the Puppet agent service with sudo puppet resource service puppet ensure=stopped.

From the installer directory, run the upgrade with sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>.

Upgrade the PE console server

In a split installation, after you upgrade PuppetDB, you’re ready to upgrade your PE console server.

Transfer the PE installation/upgrade tarball and the /etc/puppetlabs/enterprise/conf.d/ directory to the PE console node.

Unpack the PE installation/upgrade tarball. (Run tar -xf <tarball>. Note that you need about 1 GB of space in /tmp to untar the installer.)

Stop the Puppet agent service with sudo puppet resource service puppet ensure=stopped.

From the installer directory, run the upgrade with sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>.

Run Puppet on the infrastructure nodes

To complete the upgrade of your core infrastructure nodes, you need to run Puppet on all three servers.

Run Puppet in the order specified.

The Puppet master node

The PuppetDB node

The PE console node

Upgrade your remaining infrastructure and LEI nodes

Once the main components of your infrastructure are upgraded (the Puppet master, PuppetDB, and the PE console), you need to upgrade the rest of your infrastructure, including any LEI nodes, as applicable.

(If you have compile masters) Upgrade your compile masters. SSH into each compile master and run the following command:

PE client tools—install the appropriate version of client tools that matches the PE version you’ve upgraded to.

Upgrade options

When you run the upgrade, you can pass additional flags to control the upgrade.

As described above, the syntax for the upgrader with a specified pe.conf file is:

sudo ./puppet-enterprise-installer -c <FULL PATH TO pe.conf>

When you use the -c option, the pe.conf file name with full path is required. The command will quit with an error message if you omit it.

When you use the -c option, you can also use the following options:

Option

Definition

-D

The installer will display debugging information

-q

The installer will run in quiet mode. The installation process will not be displayed. If errors occur during the installation, the command will quit with an error message.

-y

The installer/upgrader will will run automatically using whatever pe.conf is in /etc/puppetlabs/enterprise/conf.d/. Note that if this file is incorrect, your upgrade will fail.

-V

The installer will display very verbose debugging information.

-h

The installer will display help information.

Checking for updates

Check here to find out the latest maintenance release of Puppet Enterprise. To see the version of PE you are currently using, run puppet --version on the command line.

Note: By default, the Puppet master checks for updates whenever the pe-puppetserver service restarts. As part of the check, it passes some basic, anonymous information to Puppet’s servers. This behavior can be disabled if need be. See Disabling update checking for details on what is collected and how to disable checking.