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.
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.
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.
/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.
-
Configure the primary server to download the agent version you want to upgrade.
- SSH into the agent node you want to upgrade.
-
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
- Most *nix
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.
<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
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.
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.
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 ). 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.
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.
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).