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, use the latest version of the puppet_agent module available from the Forge to upgrade agents. Test the upgrade on a subset of agents, and after you verify the upgrade, upgrade remaining agents.
  1. Deploy the puppet_agent module using the appropriate method, depending on how your PE installation is configured.
    • If you use Code Manager or r10k to deploy and manage your Puppet code, declare the puppet-agent module in the Puppetfile on relevant branches in your control repo. For more information about installing PE modules when you use Code Manager or r10k, see Managing modules with a Puppetfile.
    • If you do not use Code Manager or r10k, you can install the puppet_agent module by running the following command on your primary server:
      puppet module install puppetlabs-puppet_agent
  2. 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, 8.2.0). 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>/.
  3. 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.
  4. Click the link to Add membership rules, classes, and variables.
  5. 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.
  6. 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.
  7. 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 8.2.0 specifies agent version 8.2.0.
  8. 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.
  9. 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.
  1. 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, 8.2.0). 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>/.
  2. SSH into the agent node you want to upgrade.
  3. 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.
  1. Stop the Puppet service and the PXP agent service.
  2. 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
  3. Run puppet agent -t and verify that Puppet runs succeed.
  4. Restart the Puppet service and the PXP agent service.

Upgrade agents without internet access

In situations where your primary and agents are airgapped, the primary server can't download the package. Therefore, you have to download the agent tarball from an internet-connected system, prepare the airgapped primary server to serve up the agent package to your agents, and then run the upgrade script on your agents.

  1. 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.
  2. On your primary server, copy the agent tarball to the appropriate agent package directory at: /opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-<AGENT_VERSION>
  3. Declare the agent architecture class in the PE Master node group:
    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, 8.2.0). 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>/.
  4. SSH into, or physically log on to, the agent node you want to upgrade.
  5. 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
  6. Repeat these steps to upgrade additional agents.

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).

Upgrade agents using Puppet Plan

You can use the Puppet Enterprise (PE) console to upgrade agents for your specified platform. To download and upgrade an agent in the console:

  1. Go to ORCHESTRATION > Plans.
  2. In the Plans text field add enterprise_tasks::add_platforms.
  3. Under Plan parameters enter parameters and values for your plan. See Puppet Plan parameters and Puppet Plan parameters and possible values to fetch a Puppet agent.
  4. Run the plan to download the Puppet agent.
  5. SSH into the agent node you want to upgrade.
  6. 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
    Important: We recommend users do not upgrade agents on the PE server, as this may lead to unexpected errors. If users wish to upgrade agents on the PE server, they will need to upgrade to the latest PE server.
    Important: When upgrading a non-infrastructure node, be especially cautious if the node has the same platform as the PE server. It's best to avoid upgrading such agents if possible. If the upgrade is unavoidable, ensure that you run the plan again immediately after the upgrade to download the agent version that matches the PE server’s agent. This prevents any new agent from being installed on any new infrastructure node, which must have the same agent version as the PE server for smooth communication. If the plan is not re-run, the next time the Puppet agent runs, the Puppet server will downgrade the newly created infrastructure node. For example, if the PE server is running on a platform like RedHat 9 x86_64 and the non-infrastructure node has the same platform, you should avoid upgrading the agent on the non-infrastructure node.