Upgrading agents

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.
  1. On your primary server, download and install the puppetlabs-puppet_agent module: puppet module install puppetlabs-puppet_agent
  2. 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>/.

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

  4. Click the link to Add membership rules, classes, and variables.
  5. 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

  6. 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>.
  7. 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.
  8. 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.

  1. 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>/.

  2. SSH into the agent node you want to upgrade.
  3. 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 bash

      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
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.
  1. Stop the Puppet service and the PXP agent service.
  2. 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
  3. Verify that Puppet runs are complete.
  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, 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>/.
  4. SSH into, or physically log on to, the agent node you want to upgrade.
  5. 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 bash

      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
  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 version are compatible. Component versions in recent PE releases lists which Puppet agent version 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 WindowsWindows 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).