Upgrading

To upgrade your deployment, you must upgrade both the infrastructure components and agents.

The order in which you upgrade components is important. Always upgrade Puppet Server and PuppetDB simultaneously, including the puppetdb-termini package on Puppet Server nodes, and always upgrade them before you upgrade agent nodes. Do not run different major versions on your Puppet primary servers (including Server) and PuppetDB nodes.

Important: These instructions cover upgrades in the versions 5, 6 and 7 series. For instructions on upgrading from version 3.8.x, see previous versions of the documentation.

Upgrade Puppet Server

Upgrade Puppet Server to adopt features and functionality of newer versions.

Upgrading the puppetserver package effectively upgrades Puppet Server. The puppetserver package, in turn, depends on the puppet-agent package, and your node’s package manager automatically upgrades puppet-agent if the new version of puppetserver requires it.

Important: During an upgrade, Puppet Server doesn't perform its usual functions, including maintaining your site's infrastructure. If you use a single primary server, plan the timing of your upgrade accordingly and avoid reconfiguring any managed servers until your primary server is back up. If you use multiple load-balanced servers, upgrade them individually to avoid downtime or problems synchronizing configurations.

On your Puppet Server node, run the command appropriate to your package installer:
Yum:
```
yum update puppetserver
```
Apt:
```
apt-get update
apt-get install --only-upgrade puppetserver
```
If you pinned Puppet packages to a specific version, remove the pins.
For yum packages locked with the versionlock plugin, edit /etc/yum/pluginconf.d/versionlock.list to remove the lock.
On apt systems, remove .pref files from /etc/apt/preferences.d/ that pin packages, and use the apt-mark unhold command on each held package.

Upgrade agents

Regularly upgrade agents to keep your systems running smoothly.

Before you begin

Upgrade Puppet Server.

Upgrade agents using the `puppet_agent` module

Upgrade your Puppet agents using the puppetlabs/puppet_agent module. The puppet_agent module supports upgrading open source Puppet agents on *nix, Windows, and macOS

Before you begin

Install the puppetlabs/puppet_agent module. Read about installing modules in the following docs:

CAUTION: Puppet 7 changed the default digest_algorithm setting to sha256. To avoid breaking changes when upgrading, either disable remote filebuckets or make sure the agent has the same digest algorithm as server by changing the digest_algorithm setting on the agent to sha256.

To upgrade on a Puppet Server node:

Add the puppet_agent class to agents you want to upgrade.
Specify the desired puppet_agent package version and any other desired parameters described in the Forge in your site.pp file.
Note: The collection parameter is required in Open Source Puppet.
For example:
```
# site.pp 
node default {
  class { puppet_agent:
    package_version => '7.0.0',
    collection      => 'puppet7'
  }
}
```
This upgrades all of your Puppet Server managed nodes on the next agent run.

To upgrade on a node that is not managed by Puppet Server, you must declare the class in your manifest.

For example, an upgrade manifest for a non-standard source looks like:
```
# upgrade_file.pp
class { puppet_agent:
  package_version => '7.0.0.224.gaf2034af',
  yum_source      => 'http://nightlies.puppet.com/yum',
  collection      => 'puppet7-nightly'
}
```
You then need to apply the manifest: puppet apply upgrade_file.pp

Upgrade *nix agents

We recommend using the puppetlabs/puppet_agent module when upgrading between major versions of Puppet agent. To upgrade *nix without the module, you can use the system's package manager.

Before upgrading to another major version, ensure that you have installed the appropriate release package for your platform. You can find release packages for supported platforms at yum.puppet.com and apt.puppet.com. We also provide nightly release packages at nightlies.puppet.com.

On the agent node, run the command appropriate to your system's package installer:

Yum (EL/Fedora):

yum update puppet-agent

Zypper (SLES)

zypper up puppet-agent

Apt (Debian/Ubuntu):

apt-get update
apt-get install --only-upgrade puppet-agent

Upgrade Windows agents

To upgrade Windows agents without the puppetlabs/puppet_agent module, reinstall the agent using the installation instructions. You don't need to uninstall the agent before reinstalling unless you’re upgrading from 32-bit Puppet to the 64-bit version.

Upgrade macOS agents

To upgrade macOS agents without the puppetlabs/puppet_agent module, use the puppet resource command.

Before you begin

Download the appropriate agent DMG.

Use the package resource provider for macOS to install the agent from a disk image:

sudo puppet resource package "<NAME>.dmg" ensure=present source=<FULL PATH TO DMG>

Upgrade PuppetDB

Upgrade PuppetDB to get the newest features available.

Follow these steps, depending on whether you want to automate upgrade or manually upgrade.
- To automate upgrade, specify the version parameter of the puppetlabs/puppetdb module’s puppetdb::globals class.
- To manually upgrade, on the PuppetDB node, run the command appropriate to your package installer:
  Yum:
  yum update puppetdb
  Apt:
  apt-get update apt-get install --only-upgrade puppetdb
On your primary server, upgrade the puppetdb-termini package by running the command appropriate to your package installer:
Yum:
```
yum update puppetdb-termini
```
Apt:
```
apt-get update
apt-get install --only-upgrade puppetdb-termini
```

Sections

Upgrade Puppet Server

Upgrade agents

Upgrade agents using the puppet_agent module

Upgrade *nix agents

Upgrade Windows agents

Upgrade macOS agents

Upgrade PuppetDB

Upgrade agents using the `puppet_agent` module