Docs Puppet Enterprise Upgrading Upgrading agents

Upgrading agents

Sections

Upgrade agents using the puppet_agent module

Upgrade a *nix agent using a script
Upgrade a Windows agent using a script

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

Note: Before upgrading agents, verify that the primary server and agent software versions are compatible. Then after upgrade, run Puppet on your agents as soon as possible to verify that agents have the correct configuration and that your systems are behaving as expected.

Setting your desired agent version

To upgrade your primary server but use an older agent version that is still compatible with the new primary server, define a pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE> class with the agent_version variable set to your desired agent version.

To ensure your agents are always running the same version as your primary server, in the puppetlabs-puppet_agent module, set the package_version variable for the puppet_agent class to auto. This causes agents to automatically upgrade themselves on their first Puppet run after a primary server upgrade.

Upgrade agents using the puppet_agent module

The puppetlabs-puppet_agent module, available from the Forge, enables you to upgrade multiple *nixor 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.

On your primary server, download and install the puppetlabs-puppet_agent module: puppet module install puppetlabs-puppet_agent
Configure the primary server to download the agent version you want to upgrade.
1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
2. On the Classes tab, in the Add a new class field, enter pe_repo, and select the appropriate repo class from the list of classes.
  
  Repo classes are listed as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
  
  To specify a particular agent version, set the agent_version variable using an X.Y.Z format (for example, 5.5.14). When their version is set explicitly, 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
  
  The new repo is created in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.
Click Node groups, click Add group, specify options for a new upgrade node group, and then click Add.
- Parent name — Select the name of the classification node group that you want to set as the parent to this group, in this case, All Nodes.
- Group name —Enter a name that describes the role of this classification node group, for example, agent_upgrade.
- Environment — Select the environment your agents are in.
- Environment group — Do not select this option.
Click the link to Add membership rules, classes, and variables.
On the Rules tab, create a rule to add the agents that you want to upgrade to this group, click Add Rule, and then commit changes.
For example:
- Fact — osfamily
- Operator — =
- Value — RedHat
Still in the agent upgrade group, on the Classes tab, add the puppet_agent class, and click Add class.

If you don’t immediately see the class, click Refresh to update the classifier.
Note: If you’ve changed the prefix parameter of the pe_repo class in your PE Master node group, set the puppet-agent source parameter of the upgrade group to https://<PRIMARY_HOSTNAME>:8140/<Prefix>.

In the puppet_agent class, specify the version of the puppet-agent package version that you want to install, then commit changes.


Parameter	Value
package_version	The `puppet-agent` package version to install, for example `5.3.3`. Set this parameter to `auto` to install the same agent version that is installed on your primary server.

On the agents that you're upgrading, run Puppet: /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 an individual node, for example to test or troubleshoot, you can upgrade directly from the node using a script. This method relies on a package repository hosted on your primary server.

Note: If you encounter SSL errors during the upgrade process, ensure your agent's OpenSSL is up to date and matches the primary server's version. You can check the primary server's OpenSSL versions with /opt/puppetlabs/puppet/bin/openssl version and the agent's version with openssl version.

Upgrade a *nix agent using a script

You an upgrade an individual *nix agent using a script.

Configure the primary server to download the agent version you want to upgrade.
1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
2. On the Classes tab, in the Add a new class field, enter pe_repo, and select the appropriate repo class from the list of classes.
  
  Repo classes are listed as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
  
  To specify a particular agent version, set the agent_version variable using an X.Y.Z format (for example, 5.5.14). When their version is set explicitly, 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
  
  The new repo is created in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.
SSH into the agent node you want to upgrade.

Run the upgrade command appropriate to the operating system.

Most *nix

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

curl --cacert "$cacert" "$uri" | sudo bashCopied!

See Usage notes for curl examples for information about forming curl commands.

Mac OS X, Solaris, and AIX

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

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

Results

PE services restarts automatically after upgrade.

Upgrade a Windows agent using a script

You can upgrade an individual Windows agent using a script. For Windows, this method is riskier than using the puppet_agent module to upgrade, because you must manually complete and verify steps that the 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, 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
			 Copied!

Verify that Puppet runs are complete.
Restart the Puppet service and the PXP agent service.

Upgrade agents without internet access

If you don't have access to the internet beyond your infrastructure you can download the appropriate agent tarball from an internet-connected system and then upgrade using a script.

Before you begin

Download the appropriate agent tarball from an internet-connected system.

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

Upgrading the agent independent of PE

You can optionally upgrade the agent to a newer version than the one packaged with your current PE installation.

For details about Puppet agents versions that are tested and supported for PE, see the PE component version table.

The agent version is specified on a platform-by-platform basis in the PE Master node group, in any pe_repo::platform class, using the agent_version parameter.

When you install new nodes or upgrade existing nodes, the agent install script installs the version of the agent specified for its platform class. If a version isn’t specified for the node’s platform, the script installs the default version packaged with your current version of PE.

Note: To install nodes without internet access, download the agent tarball for the version you want to install, as specified using the agent_version parameter.

The platform in use on your primary server requires special consideration. The agent version used on your primary server must match the agent version used on other infrastructure nodes, including compilers and replicas, otherwise your primary server won’t compile catalogs for these nodes.

To keep infrastructure nodes synced to the same agent version, if you specify a newer agent_version for your primary server platform, you must either:

(Recommended) Upgrade the agent on your primary server—and any existing infrastructure nodes—to the newer agent version. You can upgrade these nodes by running the agent install script.
Manually install the older agent version used on your primary server on any new infrastructure nodes you provision. You can’t install these nodes using the agent install script, because the script uses the agent version specified for the platform class, instead of the primary server’s current agent version. Manual installation requires configuring puppet.conf, DNS alt names, CSR attributes, and other relevant settings.