The 2018 State of DevOps Report
Get the report

Upgrading agents

+ expand all - collapse all
+ open menu - close menu

Puppet Enterprise 2019.0

  1. Upgrade *nix or Windows agents using the puppet_agent module
  2. Upgrade a *nix or Windows agent using a script
    1. Upgrade a *nix agent using a script
    2. 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, first upgrade your master and verify that the master 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.

Upgrade *nix or Windows agents using the puppet_agent module

The puppetlabs-puppet_agent module, available from the Forge, enables you to upgrade multiple agents at once. The module handles all the latest version to version upgrades.

When upgrading agents, first test the upgrade on a subset of agents, and after you verify the upgrade, upgrade remaining agents.

  1. On your master, download and install the puppetlabs-puppet_agent module: puppet module install puppetlabs-puppet_agent
  2. Configure the master to download the agent version you want to upgrade.
    1. In the console, click Classification, and in the PE Infrastructure group, select the PE Master group.
    2. On the Configuration 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>.

    3. Click Add class and commit changes.
    4. On your master, 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 Classification, 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, click the Configuration tab, and in the Add new class field, 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://<MASTER 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.
  8. On the agents that you're upgrading, run Puppet: /opt/puppet/bin/puppet agent -t

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

Upgrade a *nix or Windows agent 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 master.

Note: If you encounter SSL errors during the upgrade process, ensure your agent's OpenSSL is up to date and matches the master's version. You can check the master'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 master to download the agent version you want to upgrade.
    1. In the console, click Classification, and in the PE Infrastructure group, select the PE Master group.
    2. On the Configuration 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>.

    3. Click Add class and commit changes.
    4. On your master, 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
      /opt/puppetlabs/puppet/bin/curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash
    • Mac OS X, Solaris, and AIX
      curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash

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 <MASTER HOSTNAME> portion of the installer script—as provided in the following example—refers to the FQDN of the master. 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://<MASTER 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.
Back to top