- Make sure you’re ready
- Review supported versions and requirements
- Install a release package to enable Puppet Collection repositories
- Repository organization
- About Puppet versions
- Confirm you can run Puppet executables
-
Install the
puppet-agent
package - Configure critical agent settings
-
Start the
puppet
service - Sign certificates on the CA master
Make sure you’re ready
Before installing Puppet on any agent nodes, make sure you’ve read the pre-install tasks and installed Puppet Server.
Note: Puppet 4 changed the locations for many of the most important files and directories. If you’re familiar with Puppet 3 and earlier, read a summary of the changes and refer to the full specification of Puppet directories.
Review supported versions and requirements
Most Linux systems (including CentOS, Redhat, Ubuntu, and Debian) have official Puppet agent packages. For a complete list of supported platforms, view the system requirements page.
Install a release package to enable Puppet Collection repositories
Release packages configure your system to download and install appropriate versions of the puppetserver
and puppet-agent
packages. These packages are grouped into a Puppet Collection repository comprised of compatible versions of Puppet tools.
Note: This document covers the Puppet Collection repository of open source Puppet 4-compatible software packages.
- For Puppet 3.8 open source packages, see its repository documentation.
- For Puppet Enterprise installation tarballs, see its installation documentation.
Puppet maintains official package repositories for several operating systems and distributions. To make the repositories more predictable, we version them as “Puppet Collections” — each collection has all of the software you need to run a functional Puppet deployment, in versions that are known to work well with each other. Each collection is opt-in, and you must choose one (and on some operating systems, install a package on Puppet-managed systems) to install software and receive updates.
Repository organization
Collection repositories are organized into two tiers that correspond to Puppet Enterprise releases, which are downstream from the collection’s open-source components:
- Numbered collections, such as Puppet Collection 1 (PC1), are long-lived, stable repositories from which long term support (LTS) Puppet Enterprise releases are built. Numbered collections maintain the same major version of each component package during its lifetime, which delivers bug fixes and minimizes breaking changes, but also introduces fewer new features.
- The “latest” collection follows every release of Puppet Enterprise, including versions not considered LTS releases, and is updated with new major-version releases that might introduce breaking changes.
Puppet publishes updates for operating systems starting from the time a package is first published for that operating system to a collection repository, and stops updating those packages 30 days after the end of the operating system’s vendor-determined lifespan.
See The Puppet Enterprise Lifecycle for information about phases of the Puppet Support Lifecycle.
About Puppet versions
Puppet’s version numbers use the format X.Y.Z, where:
- X must increase for major backwards-incompatible changes
- Y can increase for backwards-compatible new functionality
- Z can increase for bug fixes
Pinning Puppet package versions
To receive the most up-to-date Puppet software without introducing breaking changes, use the latest
collection, pin your infrastructure to known versions, and update the pinned version manually when you’re ready to update. For example, if you’re using the puppetlabs-puppet_agent
module to manage the installed puppet-agent
package, use this resource to pin it to version 1.7.0:
class { '::puppet_agent':
collection => 'latest',
package_version => '1.7.0',
}
When puppet-agent
2.0.0 is released, update package_version
when you’re ready to upgrade to that version:
class { '::puppet_agent':
collection => 'latest',
package_version => '2.0.0',
}
Package | Contents |
---|---|
puppet-agent |
Puppet, Facter, Hiera, MCollective, pxp-agent , root certificates, and prerequisites like Ruby and Augeas |
puppetserver |
Puppet Server; depends on puppet-agent |
puppetdb |
PuppetDB |
puppetdb-termini |
Plugins to let Puppet Server talk to PuppetDB |
Installing release packages on Yum-based systems
To enable the Puppet Collection 1 repository, first choose the package based on your operating system and version. The packages are located in the yum.puppetlabs.com
repository and named using the following convention:
puppetlabs-release-<COLLECTION>-<OS ABBREVIATION>-<OS VERSION>.noarch.rpm
For instance, the package for Puppet Collection 1 on Red Hat Enterprise Linux 7 (RHEL 7) is puppetlabs-release-pc1-el-7.noarch.rpm
.
Next, use the rpm
tool as root with the upgrade
(-U
) flag, and optionally the verbose
(-v
), and hash
(-h
) flags:
sudo rpm -Uvh https://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm
The rpm
tool outputs its progress:
Retrieving https://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm
Preparing... ################################# [100%]
Updating / installing...
1:puppetlabs-release-pc1-0.9.2-1.el################################# [100%]
Note: We only provide the
puppet-agent
package for recent versions of Puppet on RHEL 5, and to install it you must first download the package asrpm
on RHEL 5 doesn’t support installing packages from a URL.
Installing release packages on Apt-based systems
To enable the Puppet Collection 1 repository, first choose the package based on your operating system and version. The packages are located in the apt.puppetlabs.com
repository and named using the following convention:
puppetlabs-release-<COLLECTION>-<VERSION CODE NAME>.deb
For instance, the release package for Puppet Collection 1 on Debian 7 “Wheezy” is puppetlabs-release-pc1-wheezy.deb
. For Ubuntu releases, the code name is the adjective, not the animal.
Next, download the release package and install it as root using the dpkg
tool and the install
flag (-i
):
wget https://apt.puppetlabs.com/puppetlabs-release-pc1-wheezy.deb
sudo dpkg -i puppetlabs-release-pc1-wheezy.deb
Finally, run apt-get update
after installing the release package to update the apt
package lists.
Confirm you can run Puppet executables
The new location for Puppet’s executables is /opt/puppetlabs/bin/
, which is not in your PATH
environment variable by default.
This doesn’t matter for Puppet services — for instance, service puppet start
works regardless of the PATH
— but if you’re running interactive puppet
commands, you must either add their location to your PATH
or execute them using their full path.
To quickly add this location to your PATH
for your current terminal session, use the command export PATH=/opt/puppetlabs/bin:$PATH
. You can also add this location wherever you configure your PATH
, such as your .profile
or .bashrc
configuration files.
For more information, see our page about files and directories moved in Puppet 4.
Install the puppet-agent
package
For Yum-based systems
On your Puppet agent nodes, run sudo yum install puppet-agent
.
For Apt-based systems
On your Puppet agent nodes, run sudo apt-get install puppet-agent
.
Do not start the puppet
service yet.
Configure critical agent settings
You probably want to set the server
setting to your Puppet master’s hostname. The default value is server = puppet
, so if your master is reachable at that address, you can skip this.
For other settings you might want to change, see the list of agent-related settings.
Start the puppet
service
To start the Puppet service, run sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true
.
To manually launch and watch a Puppet run, run sudo /opt/puppetlabs/bin/puppet agent --test
.
Sign certificates on the CA master
As each Puppet agent runs for the first time, it submits a certificate signing request (CSR) to the certificate authority (CA) Puppet master. You must log into that server to check for and sign certificates. On the Puppet master:
- Run
sudo /opt/puppetlabs/bin/puppet cert list
to see any outstanding requests. - Run
sudo /opt/puppetlabs/bin/puppet cert sign <NAME>
to sign a request.
After an agent’s certificate is signed, it regularly fetches and applies configuration catalogs from the Puppet master.