Installing Puppet Agent: OS X
Included in Puppet Enterprise 2016.1.
Note: These instructions describe how to install the open source Puppet agent software on OS X.
- To install the Puppet Enterprise agent on supported operating systems, see its documentation.
- To install the open source agent on Linux distributions that don’t have official packages, review Puppet’s prerequisites.
- To install the open source agent on Windows operating systems, see the Windows installation instructions.
- To install the open source agent on Linux distributions, see the Linux installation instructions.
- To install open source Puppet Server on a Puppet master, see its documentation.
Make sure you’re ready
Note: Puppet 4 changes 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
Puppet agent is distributed in a package that includes all of Puppet’s prerequisites. You don’t need to download anything else to install Puppet agent on a node. These packages are tied to a Puppet Collection (PC), which is a set of Puppet 4 software designed and tested to work well together.
We publish and test official
puppet-agent installers for the following OS X versions:
- 10.11 El Capitan
- 10.10 Yosemite
- 10.9 Mavericks
Download the OS X
puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of
package-agent you install is compatible with the Puppet Collection powering your infrastructure.
puppet-agent for Puppet Collection 1:
You can also download older versions of Puppet from downloads.puppetlabs.com. Browse to
<OS X VERSION>/PC1/x86_64 for the most recently released packages. For example, the path to the PC1 package for OS X 10.11 is
Choosing a package
Packages are named according to their
puppet-agent version and compatible OS X version. They also contain a release number — typically
1 — that represents the iteration of that version’s package.
puppet-agent-<PACKAGE VERSION>-<RELEASE NUMBER>.osx<OS X VERSION>.dmg
For example, the filename for the first release of the
puppet-agent 1.4.2 package on OS X 10.11 is:
To see which versions of Puppet, its related tools, and required components are in a given
puppet-agent release, as well as release notes for each release, see About Puppet agent.
Previous package names
We used different naming schemes in the
puppet-agent1.2 series before settling on the current convention used since 1.2.5.
- 1.2.0 through 1.2.2:
puppet-agent-<PACKAGE VERSION>-osx-<OS X VERSION>-<ARCH>.dmg. Redundant; OS X only runs on x86_64.
puppet-agent-<PACKAGE VERSION>-<OS X CODE NAME>.dmg. This was too hard for automated tooling to deal with, because OS X’s built-in CLI tools don’t report the code name.
Make sure 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, so enabling or disabling Puppet agent with
launchctl works fine. However, to run interactive
puppet commands, either add the location to your
PATH or refer to the executables by their full locations.
For more information, see our page about files and directories moved in Puppet 4.
There are three ways to install Puppet on OS X:
Regardless of which method you choose, the
mcollective services launch automatically once they’re installed. You can disable these services with
launchctl or by running:
sudo puppet resource service <SERVICE NAME> ensure=stopped enable=false
Installing with the GUI
To install Puppet with a graphic user interface:
puppet-agentdisk image you downloaded.
OS X verifies the image, and then mounts it at
/Volumes/<DMG NAME>. A Finder window then appears showing the image’s contents: a single
puppet-agent-<PACKAGE VERSION>-<RELEASE NUMBER>-installer.pkgfile.
Double-click the package file, and then follow the installer prompts.
Once the installation is complete, the
mcollectiveservices launch automatically.
Unmount the disk image. You can then delete the image.
Installing on the command line
You can use the
installer commands to mount the disk image, and then install the package from the command line.
Mount the disk image by running:
sudo hdiutil mount <DMG FILE>
.pkgfile in the mounted volume and install it by running:
sudo installer -pkg /Volumes/<IMAGE>/<PKG FILE> -target / Once the installation is complete, the `puppet` and `mcollective` services launch automatically.
Unmount the disk image by running:
sudo hdiutil unmount /Volumes/<IMAGE>
You can then delete the disk image.
Upgrading with Puppet
If you already have Puppet installed, you can use the
puppet resource command to upgrade with fewer steps.
puppet-agentdisk image you downloaded, and note both the filename and its full path on disk.
Have Puppet install the package by running:
sudo puppet resource package "<IMAGE NAME>.dmg" ensure=present source=<FULL PATH TO IMAGE>
Configure critical agent settings
Set the agent’s
server setting to your Puppet master’s hostname. The default value is
server = puppet, so if your master’s hostname is already
puppet, you can skip this step.
See the list of agent-related settings for more configuration options.
Test Puppet agent
By default, the
puppet service performs a Puppet run every 30 minutes. To manually launch and watch a Puppet run, run:
sudo puppet agent --test
Sign certificates on the CA master
As each agent attempts its first run, it submits a certificate signing request (CSR) to the certificate authority (CA) Puppet master. The CA master must sign these certificates before it can manage the agents.
To do this:
Log into the CA Puppet master.
View outstanding requests by running:
sudo puppet cert list
Sign a request by running:
sudo puppet cert sign <NAME>
Once the Puppet master signs an agent’s certificate, the agent regularly fetches and applies configuration catalogs from the master.
Note: The Puppet documentation includes a detailed description of Puppet’s agent/master communications.