Upgrading Puppet Enterprise: Notes and Warnings

A newer version is available; see the version menu above for details.

IMPORTANT: READ BEFORE UPGRADING: If you are upgrading from PE 3.3 and you use the PE console for node classification, follow the steps in the node classification migration process doc to perform your upgrade to PE 3.8.

Note: A complete list of known issues is provided in the PE 3.8 release notes. Please review this list before upgrading.

Upgrading to PE 3.8? Make sure you’re on the correct version. Upgrades to PE 3.8 are only supported from PE 3.3.2 or from any version in the 3.7 series.

Upgrading to the Puppet Server (on the Puppet Master)

PE 3.8 uses the Puppet Server, running the Puppet Master, which functions as a seamless drop-in replacement for the former Apache/Passenger Puppet master stack. However, due to this change in the underlying architecture of the Puppet master, there are a few changes you’ll notice after upgrading that we’d like to point out. Refer to About the Puppet Server for more information.

Updating Puppet Master Gems

See the known issue about Ruby gems and upgrades in the release notes.

Upgrading to Directory Environments

Directory environments are enabled by default in PE 3.8.0. Before upgrading be sure to read Important Information about Upgrades to PE 3.8 and Directory Environments.

Warnings: If you enabled directory environments in PE 3.3.2 or 3.7.x and are upgrading to PE 3.8.0, ensure there is no default_manifest parameter in puppet.conf before upgrading. Upgrades will fail if this change is not made.

If you enabled directory environments in PE 3.3.2 or 3.7.x and are upgrading to PE 3.8.0, ensure that the basemodulepath parameter in puppet.conf is set in the [main] section and not in the [master] section before upgrading. Upgrades will fail if this change is not made.

Upgrading to the Node Classifier

PE 3.8.0 uses the new node classifier, which replaces previous versions of the PE console node classifier and changes the way you classify agent nodes.

If you are upgrading and you use the PE console for node classification, follow the steps in the node classification migration process doc BEFORE performing your upgrade. The steps in the migration process doc provide a smooth upgrade path from PE 3.3.2 to PE 3.8.

Please note that factors such as the size of your deployment and the complexity of your classifications will determine how much time and/or planning you will need before upgrading to PE 3.8.

For more information about the node classifier, refer to Getting Started With Classification.

A Note about RBAC, Node Classifier, and External PostgreSQL

If you are using an external PostgreSQL instance that is not managed by PE, please note the following:

  1. You will need to create databases for RBAC, activity service, and the node classifier before upgrading. Instructions on creating these databases are documented in the web-based installation instructions for both monolithic and split installs.
  2. You will need to have the citext extension enabled on the RBAC database.

About the Agent-specified Group

If you have agent nodes that specify their own environments, those nodes will be pinned, not only to a group named for that node, but also to the “agent-specified” group in the node classifier. While this is done to ensure your agent nodes can still have an agent-specified environment, we recommend moving to a model where classification of nodes is performed by the node classifier.

For example, if you have an agent node for which the [agent] section of puppet.conf contains environment=development, we recommend you use the node classifier to change its group environment to “development” and then unpin it from the “agent-specified” group.

Adding Nodes to Preconfigured PE Groups

For fresh installations of PE 3.8, there are some special infrastructure node groups that are created and configured during the installation process. For upgrades, if these groups do not exist, or do not contain any classes, they will be created and configured but no nodes will be pinned to them. This helps prevent errors during the upgrade process, but you must manually pin the correct nodes to each group after you complete the upgrade process.

The preconfigured groups doc has a list of the preconfigured node groups and classification data that come preconfigured in fresh installs.

If these groups do exist during upgrade and contain all the classes documented in the preconfigured groups doc, they will not be modified during the upgrade process.

If these groups do exist but only contain some of the documented classes, or contain other unknown classes, they will not be modified, and the upgrade process will fail. Before upgrading, please ensure that either you have no classes in the PE groups or that they match the preconfigured groups doc.

After upgrading you must pin nodes to the new PE groups. We recommend that you perform the manual pinning in this order:

  1. The PE Certificate Authority node group (typically the same as your Puppet master)
  2. The PE Master node group
  3. The PuppetDB node group
  4. The PE Console node group
  5. The PE ActiveMQ Broker node group (typically your Puppet master)

If you pin the node groups in this order, you do not need to stop/restart Puppet.

The MCollective node group is configured during upgrade, so you do not need to perform any classification or pinning with this group.

To pin a node to a node group in the PE console:

  1. In the Rules tab, scroll down to the pinned nodes section below the rules.
  2. In the Certname field, enter the certname of the node.
  3. Click Pin node, and then click the commit button.

Upgrading to Role-Based Access Control (RBAC)

After upgrading to PE 3.8, you will need to set up your directory service and users and groups. Note that when you upgrade, PE doesn’t migrate any existing users. In addition, PE doesn’t preserve your username and password. You’ll now log in with “admin” as your username.

For more information about RBAC, refer to Working with Role-Based Access Control.

Upgrading to 3.8 with a Modified auth.conf File

The auth.conf file manages access to Puppet’s HTTPS API. This file is located at /etc/puppetlabs/puppet/auth.conf on the Puppet master.

If we find a modified auth.conf during the 3.8 upgrade process, we will attempt to create a diff between your modified version and the 3.8 version (reliant on the presence of a diff executable on your Puppet master server). You may need to modify your auth.conf to address the differences, as this file is not managed by PE. We recommend that you consider and address the changes, as some functionality (e.g., console services) may not be available after upgrade if the endpoints aren’t authorized.

Here are some notable changes that have been made to the endpoints in auth.conf:

  • The /v2.0/environments endpoint was added (3.3).

  • The certificate_status endpoint was removed (3.7.2).

  • The resource_type endpoint was modified to allow classifier_client_certname (pe-internal-classifier) and console_client_certname (pe-internal-dashboard) (3.7.0).

Note that access to the CA functions of the Puppet master is no longer managed with auth.conf; it is now managed by ca.conf in the Puppet Server configuration files.

You will need to acknowledge you’re aware of the differences when prompted by the upgrader, or pass in an answer file with q_exit_and_update_auth_conf in it when running the upgrade.

q_database_host Cannot be an Alt Name For Upgrades to 3.8

PostgreSQL does not support alt names when set to verify_full. If you are upgrading to 3.8 with an answer file, make sure q_database_host is set as the Puppet agent certname for the database node and not set as an alt name.

Before Upgrading, Correct Invalid Entries in autosign.conf

Any entries in /etc/puppetlabs/puppet/autosign.conf that don’t conform to the autosign requirements will cause the upgrade to fail to configure the PE console. Please correct any invalid entries before upgrading to PE 3.8.

Hard Tabs For Indentation In Hiera YAML Files Cause Errors After Upgrading

If you’re upgrading to the PE 3.8.x series, ensure that any Hiera YAML files do not include hard tabs for indentation. Hard tabs in these files will cause errors after upgrading.

You Might Need to Upgrade puppetlabs-inifile to Version 1.1.0 or Later

PE will automatically update your version of puppetlabs-inifile as part of the upgrade process. However, if you encounter the following error message on your PuppetDB node, then you need to manually upgrade the puppetlabs-inifile module to version 1.1.0 or higher.

Error: Could not retrieve catalog from remote server: Error 400 on SERVER: Invalid parameter quote_char on Ini_subsetting['-Xmx'] on node master
Warning: Not using cache on failed catalog
Error: Could not retrieve catalog; skipping run

↑ Back to top