Installing Puppet
Sections
To get started using Puppet Core, you must first complete the initial installation and setup process.
Puppet is distributed in
several packages. These include puppetserver
,
puppet-agent
and puppetdb
. Puppet Server controls the
configuration information for one or more managed agent nodes. PuppetDB is where the data
generated by Puppet is
stored.
-
Enabling the Puppet platform repository
-
Installing Puppet Server
-
Installing Puppet agent
- Installing PuppetDB (optional)
puppetserver
component
of the Puppet platform is available only for Linux. The puppet-agent
component is available
independently for more than 30 platforms and architectures, including Windows and macOS.
For more information on Puppet packages, see
Puppet platform lifecycle.
1. Enable the Puppet platform repository
Enabling the Puppet platform repository makes the components needed for installation available on your system. The process for enabling the repository depends on your package management system, such as Yum or Apt.
Identify the URL of the package you want to enable based on your operating system and version. *nix platform packages are located in Puppet.com repositories corresponding to the Yum and Apt package management systems.
Package or artifact type | Location |
---|---|
Yum | https://yum-puppetcore.puppet.com |
Apt | https://apt-puppetcore.puppet.com |
Microsoft Windows and macOS | https://artifacts-puppetcore.puppet.com |
Puppet and Facter gems | https://rubygems-puppetcore.puppet.com
|
https://yum-puppetcore.puppet.com/public/<PLATFORM_NAME>-release-<OS_ABBREVIATION>-<OS_VERSION>.noarch.rpm
Copied!
For
example:https://yum-puppetcore.puppet.com/public/puppet8-release-el-8.noarch.rpm
Copied!
https://apt-puppetcore.puppet.com/public/<PLATFORM_VERSION>-release-<VERSION_CODE_NAME>.deb
Copied!
For
example:https://apt-puppetcore.puppet.com/public/puppet8-release-jammy.deb
Copied!
Note that for Ubuntu releases, the VERSION_CODE_NAME
is the adjective, not the animal.Enable the Puppet platform on Yum
The procedure for enabling the Puppet platform on Yum differs, depending on the operating system of the packages that you want to install.
- Install the Puppet GPG
key:
curl -LO https://yum-puppetcore.puppet.com/public/RPM-GPG-KEY-puppet-20250406
Copied! - Install the SUSE Linux Enterprise Server release
package:
rpm -Uvh https://yum-puppetcore.puppet.com/public/puppet8-release-sles-15.noarch.rpm
Copied! - Add credentials to the
/etc/zypp/credentials.d/PuppetcoreCreds
file, whereforge-key
is a string literal and<API_KEY>
is your API key from Puppet Forge:username=forge-key password=<API_KEY>
Copied! - Install the agent by following the instructions in Installing and configuring agents.
To install packages that are not associated with SUSE Linux Enterprise Server, complete the following steps:
Enable the Puppet platform on Apt
- If you install from the Puppet Yum and Apt repositories, the release package that enables the repository also installs our release signing key. The Yum and Apt tools automatically verify the integrity of packages as you install them.
- If you install a Windows agent using an
.msi
package, the Windows installer automatically verifies the signature before installing the package. - If you install a
.dmg
package on macOS, the installer automatically verifies the signature before installing the package.
If you need to manually verify packages, see Verify packages.
Enable the Puppet platform by using CLI clients
You can enable the Puppet platform by using command-line interface (CLI) clients such as Client URL (curl) and World Wide Web Get (Wget).
CLI clients can be used to download only Puppet Agent packages.
Authentication credentials
Because Puppet Core packages are stored in a protected repository, you must authenticate to access and download the packages.
Use the string literal forge-key
as the username. Use your Puppet Forge API key as the password.
Authentication procedures
- Create and configure a
.netrc
file - Export credentials to environment variables
Create and configure a .netrc
file
A .netrc
file is a configuration file used by many command-line
tools and programs, including curl, FTP, and Git. The primary purpose of the file is
to store login credentials.
.netrc
file: - Create file named
.netrc
by running the following commands:touch ~/.netrc chmod 600 ~/.netrc
Copied! - Edit the file to add your
credentials:
machine artifacts-puppetcore.puppet.com login forge-key password <API_KEY>
Copied! - Run a command with the
--netrc
option so that the credentials stored in the.netrc
file are used for authentication, as shown in the following example:curl --netrc 'https://artifacts-puppetcore.puppet.com/v1/download?os_name=ubuntu&os_version=22.04&version=8.9.0&os_arch=amd64' -J -O
Copied!
Export credentials to environment variables
- Export the credentials:
export USERNAME=forge-key export PASSWORD=<API_KEY>
Copied! - Call the credentials from the URL, as shown in the following
example:
curl -u $USERNAME:$PASSWORD https://artifacts-puppetcore.puppet.com/v1/download?param1=value1¶m2=value2
Copied!
Request parameters
The following request parameters are accepted by the artifact download endpoint.
Name | Type | Default | Example | Description |
---|---|---|---|---|
version | String | None | 8.11.0 | The package version. |
os_name | String | None | amazon | The name of the operating system. For a list of valid names, see Table 3. |
os_version | String | None | 2023 | The operating system version. For a list of valid versions, see Table 3. |
os_arch | String | None | aarch64 | The operating system architecture. For a list of valid architectures, see Table 3. |
Operating system names, versions, and architectures
The following table lists currently valid values for the os_name
, os_version
, and os_arch
parameters.
To specify an operating system, use the values in the Name column. The Full name column is for informational purposes only.
Name | Full name | Version | Architecture |
---|---|---|---|
amazon | Amazon Linux | 2, 2023, and so on | x86_64, aarch64 |
debian | Debian | 10, 11, and so on | amd64, arm64 |
el | Red Hat Enterprise Linux | 7, 8, and so on | x86_64, aarch64, ppc64le |
fedora | Fedora Linux | 40 and so on | x86_64 |
osx | macOS | 14 and so on | x86_64, arm64 |
sles | SUSE Linux Enterprise Server | 12, 15 | x86_64 |
ubuntu | Ubuntu | 22.04 and so on | amd64, arm64 |
windows | Microsoft Windows | Ignored | x86, x64 |
Example
-
<username>
is a string literal,forge-key
-
<password>
is the API key generated in Puppet Forge
curl -J -O -u <username>:<password> "https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&os_name=ubuntu&os_version=22.04&os_arch=amd64"
Copied!
Content disposition
–J –O
only with
curl. For wget, use the following
structure:wget --content-disposition <URL>
Copied!
Install gems (optional)
In some cases, you might have to install Puppet or Facter gems. For example, if you plan to develop modules, you must install gems. Gems are accessed from a protected repository that requires authentication.
Gems are available from the following protected repository:
https://rubygems-puppetcore.puppet.com
To access gems, you must configure your credentials as environment variables. Then,
you can use the Gem
client or the Bundle
client
to install the gems.
Prerequisites
These prerequisites apply regardless of whether you use the Gem
client or the Bundle
client.
<API_KEY>
is a variable and forge-key
is a
string literal:export USERNAME=forge-key
export PASSWORD=<API_KEY>
Copied!
Install gems with the Gem client
With the Gem
client, you can use the following installation
procedure.
- In the
~/.gemrc
file, add thepuppetcore
source and credentials, where<API_KEY>
is the key that you obtained from Puppet Forge, as described in Accessing Puppet Core for limited use::sources: - "https://forge-key:<API_KEY>@rubygems-puppetcore.puppet.com" - "https://rubygems.org"
Copied! - Install gems by following your typical process, for
example:
gem install puppet
Copied!
Install gems with the Bundle client
With the Bundle
client, you must add the Bundler
configuration to download gems from the protected repository.
Bundler
can then authenticate during the download process.
- Run the following
command:
bundle config set --global https://rubygems-puppetcore.puppet.com $USERNAME:$PASSWORD
Copied! - Specify the gem source block in the
Gemfile:
source "https://rubygems-puppetcore.puppet.com" do gem 'puppet' end
Copied! - To access the protected repository and install the gem, run the following
command:
bundle install
Copied!
2. Install Puppet Server
Puppet Server is a required application that runs on the Java Virtual Machine (JVM) on the primary server.
In addition to hosting endpoints for the certificate authority service, Puppet Server also powers the catalog compiler, which compiles configuration catalogs for agent nodes, using Puppet code and various other data sources.
In this section, you will install the puppetserver
package and start the service.
Follow the steps in install Puppet Server
3. Install Puppet agent
Puppet agents translate code into commands and then execute it on the systems you specify.
In this section, you will install agents on your chosen operating system, configure them, and sign their certificates. Follow the steps in install agents.
4. Install PuppetDB (optional)
All of the data generated by Puppet is stored in PuppetDB.
You can optionally install PuppetDB to enable extra features, including enhanced queries and reports about your infrastructure. In this section, you will assign PuppetDB module’s classes to your servers. Follow the steps in install PuppetDB.