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
puppet.confbefore 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
puppet.confis 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:
- 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.
- 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
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:
- The PE Certificate Authority node group (typically the same as your Puppet master)
- The PE Master node group
- The PuppetDB node group
- The PE Console node group
- 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:
- In the Rules tab, scroll down to the pinned nodes section below the rules.
- In the Certname field, enter the certname of the node.
- 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 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
/v2.0/environmentsendpoint was added (3.3).
certificate_statusendpoint was removed (3.7.2).
resource_typeendpoint was modified to allow
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
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