Upgrading agents

Upgrade your agents as new versions of Puppet Enterprise (PE) become available. The puppet_agent module helps automate upgrades, and provides the safest upgrade. Alternatively, you can use a script to upgrade individual nodes.

Important: Before upgrading agents, verify that the primary server and agent software versions are compatible. Component versions in recent PE releases lists which Puppet agent versions are tested and supported for each PE release.

After upgrading, run Puppet on your agents (such as with puppet agent -t) as soon as possible to verify that the agents have the correct configuration and your systems are behaving as expected.

Upgrade agents using the `puppet_agent` module

You can use the puppet_agent module to upgrade multiple *nix, macOS, or Windows agents at one time. The module handles all the latest version-to-version upgrades.

Important: For the most reliable upgrade, always use the latest version of the puppet_agent module to upgrade agents. Test the upgrade on a subset of agents, and after you verify the upgrade, upgrade remaining agents.

Download the puppet_agent module from the Forge.
On your primary server, install the puppet_agent module by running: puppet module install puppetlabs-puppet_agent
Configure the primary server to download the agent version you want to upgrade to.
1. In the PE console, go to Node groups > PE Infrastructure > PE Master.
2. On the Classes tab, enter pe_repo in the Add a new class field, and select the appropriate repo class from the list of classes.
  
  Repo classes are formatted as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
  
  To use a specific agent version, set the agent_version variable using an X.Y.Z format (for example, 5.5.14). If you specify a version in this way, agents do not automatically upgrade when you upgrade your primary server.
3. Click Add class and commit changes.
4. On your primary server, run Puppet to configure the newly assigned class: puppet agent -t
  A new agent package repo is created at /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.
Create an agent upgrade node group.
1. Go to Node groups > Add group.
2. Set the Parent name to the name of the classification node group that is the parent of this group, such as All Nodes.
3. Enter a Group name describing the classification node group's role, such as agent_upgrade.
4. Select the Environment your agents are in.
5. Do not select the Environment group option.
6. Click Add.
Click the link to Add membership rules, classes, and variables.
On the Rules tab, create one or more rules to add the agent nodes you want to upgrade to this group, click Add Rule, and then commit changes.
Dynamically add nodes to a node group provides detailed instructions for creating node group rules.
Go to the Classes tab for the agent node upgrade group, add the puppet_agent class, and click Add class. You might need to click Refresh to update the classifier.
Locate the puppet_agent class you just added. Select the package_version parameter, set the Value to the puppet-agent package version you want to install, then commit changes.
If you want to automatically install the same agent version as your primary server, set the Value to auto. To install a specific version, enter the version number in X.Y.Z format. For example, setting the Value to 5.3.3 specifies agent version 5.3.3.
If you changed the prefix parameter for the pe_repo class in the PE Master node group, you must communicate this to the agent upgrade node group. To do this, on the agent upgrade node group, set one of the *_source parameters for the puppet_agent class to https://<PRIMARY_HOSTNAME>:8140/<PREFIX>. Go to the puppet_agent module's Forge page for descriptions of the various *_source parameters.
Run Puppet on the agents you're upgrading, such as: /opt/puppet/bin/puppet agent -t

Results

After the Puppet run, you can verify the upgrade with: /opt/puppetlabs/bin/puppet --version

Upgrade agents using a script

To upgrade the agent on an individual node, you can use a script to upgrade directly from the node. This method relies on a package repository hosted on your primary server.

Tip: If you encounter SSL errors during the upgrade process, make sure the agent node's OpenSSL is updated and matches the primary server's OpenSSL version. Use these commands check OpenSSL versions:

For the primary server: /opt/puppetlabs/puppet/bin/openssl version
For agent nodes: openssl version

Upgrade a *nix agent using a script

You can use a script to upgrade individual *nix agents.

For general information about forming curl commands and authentication in commands, go to Using example commands.

Configure the primary server to download the agent version you want to upgrade to.
1. In the PE console, go to Node groups > PE Infrastructure > PE Master.
2. On the Classes tab, enter pe_repo in the Add a new class field, and select the appropriate repo class from the list of classes.
  
  Repo classes are formatted as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
  
  To use a specific agent version, set the agent_version variable using an X.Y.Z format (for example, 5.5.14). If you specify a version in this way, agents do not automatically upgrade when you upgrade your primary server.
3. Click Add class and commit changes.
4. On your primary server, run Puppet to configure the newly assigned class: puppet agent -t
  A new agent package repo is created at /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.
SSH into the agent node you want to upgrade.

Run the upgrade script command:

cacert="$(puppet config print localcacert)"
uri="https://$(puppet config print server):8140/packages/current/install.bash"

curl --cacert "$cacert" "$uri" | sudo bash

Results

PE services restart automatically after upgrade.

Upgrade a Windows agent using a script

You can use a script to upgrade individual Windows agents.

CAUTION: For Windows, this method is riskier than when you Upgrade agents using the puppet_agent module, because you must manually perform actions and verifications that the puppet_agent module handles automatically.

Note: The <PRIMARY_HOSTNAME> portion of the installer script—as provided in the following example—refers to the FQDN of the primary server. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.

Stop the Puppet service and the PXP agent service.

On the Windows agent, open PowerShell as an administrator and run the install script:

[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; `
$webClient = New-Object System.Net.WebClient; `
$webClient.DownloadFile('https://<PRIMARY_HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); `
.\install.ps1

Run puppet agent -t and verify that Puppet runs succeed.
Restart the Puppet service and the PXP agent service.

Upgrade agents without internet access

You can download the agent tarball from an internet-connected system and use a script to upgrade airgapped agents.

Before you begin

Download the appropriate agent tarball.

If you are installing an agent version that is different from your primary server, make sure you download the agent tarball corresponding to the agent_version parameter for the node's platform, as explained in Setting agent versions.

On your primary server, copy the agent tarball to the appropriate agent package directory at /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>
Run Puppet: puppet agent -t
Follow the steps to Upgrade agents using a script.

Setting agent versions

Usually, you want your agent nodes to run the same agent version as the primary server; however, if absolutely necessary, agent nodes can run a different, but compatible, version.

Important: Make sure the primary server and agent versions are compatible. Component versions in recent PE releases lists which Puppet agent versions are tested and supported for each PE release.

If you Upgrade agents using the puppet_agent module, you specify the agent version by setting the package_version parameter on the agent upgrade node group. You can define a specific version or set this to auto, if you want your agents to always run the same version as your primary server. When set to auto, agent nodes to automatically upgrade themselves on their first Puppet run after a primary server upgrade. You can also set the package_version parameter for the puppet_agent class in the puppet_agent module's configuration.

The agent version can be specified on a platform-by-platform basis by the agent_version parameter of any pe_repo::platform classes in the PE Master node group (at Node Groups > PE Master > Classes). If your nodes run on various platforms, you must set the agent_version on each pe_repo class that you want to use a specific agent version. For example, you can specify different versions for 32-bit and 64-bit Windows agents.

CAUTION: Setting agent_version blocks upgrades. Setting this parameter is only recommended in specific scenarios with strong justification for doing so.

Never set agent_version for infrastructure nodes. Critical failures can occur if all your infrastructure nodes, including the primary server, compilers, and replicas, aren't running the same agent version.

When you install or upgrade agent nodes, the agent install script looks at the node's platform class and installs the specified agent version. If you don't specify a version for a platform, the script installs the default version packaged with your current version of PE. If you specified an older version for your agent platforms, you could upgrade your primary server while maintaining an older agent version on your agent nodes. Similarly, if you specified a newer version for your agent platforms, your agent nodes would run a newer agent version than your primary server.

CAUTION:

The primary server's agent version must match the agent version on other infrastructure nodes, including compilers and replicas, otherwise your primary server won’t compile catalogs for those nodes. Not compiling catalogs is a critical failure. Never set agent_version on any infrastructure node (including the primary server, compilers, and replicas).