Upgrade agents using the puppet_agent module

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

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

Related information

• Declare classes