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.
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.
puppet_agent
module to upgrade agents. Test the
upgrade on a subset of agents, and after you verify the upgrade, upgrade remaining
agents./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.
- 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.
PE services restart automatically after upgrade.
Upgrade a Windows agent using a script
You can use a script to upgrade individual Windows agents.
puppet_agent
module handles automatically.<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.Upgrade agents without internet access
You can download the agent tarball from an internet-connected system and use a script to upgrade airgapped agents.
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.
-
On your primary server, copy the agent tarball to the appropriate agent package
directory at
/opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>
-
Run Puppet:
puppet agent -t
- Follow the steps to Upgrade agents using a script.
Setting agent versions
Usually, you want your agent nodes to run the same agent version as the primary server; however, if necessary, agent nodes can run a different, but compatible, version. It is also possible to upgrade the primary server agent to a newer version than that packaged with your current Puppet Enterprise (PE) installation.
The agent version is 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 ). 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.
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.
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.
Mismatches can happen when, for example, an infrastructure node runs on a different
platform than your primary server, and the primary server platform's agent_version
is ahead or behind the node platform's
agent_version
.
agent_version
for your primary server's
platform, you must either:- (Recommended) Upgrade the agent on your primary server and any existing infrastructure nodes to the newer agent version. Use the agent install script to upgrade these nodes individually, as explained in Upgrade agents using a script and Install agents with the install script.
- If the primary server runs an older agent version, you must manually install
the older agent version (used on the primary server) on any new
infrastructure nodes, and you must make sure your existing infrastructure
nodes match primary server's version. You can't use the agent install script
for this because the script uses the agent version specified for the node's
pe_repo::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. Although you can't use the install script for this, you can find helpful information about these settings in Customize the install script. - For information about various manual installation options, go to
Install *nix agents, Install Windows agents, or Install macOS agents. You must use a method that
requires downloading a specific agent tarball and does not rely on
the
pe_repo::platform
class. - If you downgraded the primary server's agent version after an
upgrade, you might need to downgrade the agent version on your
existing infrastructure nodes if their platform classes do not
specify a static
agent_version
.
- Manual installation requires configuring
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.