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.

This guide walks you through the following steps in installing Puppet Core:
  • Enabling the Puppet platform repository

  • Installing Puppet Server

  • Installing Puppet agent

  • Installing PuppetDB (optional)
You install each of these components separately, operating on a single node. From here, you can scale up to the large installation as your infrastructure grows, or customize configuration as needed.
Restriction: The 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.

Before you begin

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.

Ensure that you download packages and artifacts from the current location, as listed in the table.
Table 1. Package and artifact locations
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
Yum is used with RPM-based operating systems, such as Red Hat Enterprise Linux (RHEL), Fedora, Amazon Linux, and SUSE Linux Enterprise Server (SLES). Go to https://yum-puppetcore.puppet.com/public for a list of packages and corresponding URLs. The Yum package URL naming convention is generally:
https://yum-puppetcore.puppet.com/public/<PLATFORM_NAME>-release-<OS_ABBREVIATION>-<OS_VERSION>.noarch.rpmCopied!
For example:
https://yum-puppetcore.puppet.com/public/puppet8-release-el-8.noarch.rpmCopied!
Apt is used with Debian and Ubuntu. Go to https://apt-puppetcore.puppet.com/public for a list of packages and corresponding URLs. The Apt package URL naming convention is generally:
https://apt-puppetcore.puppet.com/public/<PLATFORM_VERSION>-release-<VERSION_CODE_NAME>.debCopied!
For example:
https://apt-puppetcore.puppet.com/public/puppet8-release-jammy.debCopied!
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.

For SUSE Linux Enterprise Server packages, complete the following steps:
  1. Install the Puppet GPG key:
    curl -LO https://yum-puppetcore.puppet.com/public/RPM-GPG-KEY-puppet-20250406Copied!
  2. Install the SUSE Linux Enterprise Server release package:
    rpm -Uvh https://yum-puppetcore.puppet.com/public/puppet8-release-sles-15.noarch.rpmCopied!
  3. Add credentials to the /etc/zypp/credentials.d/PuppetcoreCreds file, where forge-key is a string literal and <API_KEY> is your API key from Puppet Forge:
    username=forge-key 
    password=<API_KEY>Copied!
  4. 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:

  1. Run the RPM tool in upgrade mode:
    sudo rpm -U <PACKAGE_URL>Copied!
    For example, to enable the Enterprise Linux 8 repository:
    sudo rpm -Uvh https://yum-puppetcore.puppet.com/public/puppet8-release-el-8.noarch.rpmCopied!
  2. Uncomment and update the username and password in the /etc/yum.repos.d/<file_name>.repo file:
    #username=forge-key 
    
    #password=<API_KEY>Copied!
    Important: forge-key is a string literal.

    See the following example.

    $ sudo vi /etc/yum.repos.d/puppet8-release.repo 
    [puppet8] 
    name=Puppet 8 Repository el 8 - $basearch 
    baseurl=https://yum-puppetcore.puppet.com/puppet8/el/8/$basearch 
    gpgkey=file:///etc/pki/rpm-gpg/<gpg_key> 
    enabled=1 
    gpgcheck=1 
    ## Add authentication here by uncommenting and filling in values 
    username=forge-key 
    password=<API_KEY>Copied!

Enable the Puppet platform on Apt

  1. Download the package and run the dpkg tool in install mode:
    wget --content-disposition <PACKAGE_URL>
    sudo dpkg -i <FILE_NAME>.debCopied!
    For example, to enable the Ubuntu focal repository:
    wget --content-disposition
    https://apt-puppetcore.puppet.com/public/puppet8-release-focal.deb 
    sudo dpkg -i puppet8-release-focal.deb Copied!
  2. Edit the /etc/apt/auth.conf.d/<file_name>.conf file to add the credentials:
    #login forge-key
    #password <API_KEY>Copied!
    Important: forge-key is a string literal.
    See the following example.
    $ sudo vi /etc/apt/auth.conf.d/apt-puppetcore-puppet.conf   
    machine apt-puppetcore.puppet.com 
    login forge-key 
    password <API_KEY> Copied!
  3. Update the package lists:
    sudo apt-get updateCopied!
Results
Certain operating systems and installation methods automatically verify package signatures. In these cases, you don’t need to do anything to verify the package signature. These methods include:
  • 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).

Restriction:

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

You can use either of the following procedures to authenticate:
  • 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.

Complete the following steps to create and configure a .netrc file:
  1. Create file named .netrc by running the following commands:
    touch ~/.netrc 
    chmod 600 ~/.netrcCopied!
  2. Edit the file to add your credentials:
    machine artifacts-puppetcore.puppet.com  
      login forge-key 
      password <API_KEY>Copied!
  3. 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 -OCopied!

Export credentials to environment variables

You can directly curl the endpoints with credentials by completing the following steps:
  1. Export the credentials:
    export USERNAME=forge-key  
    export PASSWORD=<API_KEY> Copied!
  2. 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&param2=value2Copied!

Request parameters

The following request parameters are accepted by the artifact download endpoint.

Table 2. Request parameters
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.

Table 3. Operating system names, versions, and architectures
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

A download link for Ubuntu Linux 22.04 would be similar to the following example, where:
  • <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

Content disposition is enabled for these packages and can be used while downloading packages to store them with their default name. Use –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.

Configure your credentials as environment variables, where <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.

To configure the new gem source globally and then install the gem, complete the following steps:
  1. In the ~/.gemrc file, add the puppetcore 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!
  2. Install gems by following your typical process, for example:
    gem install puppetCopied!

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.

Complete the following steps:
  1. Run the following command:
    bundle config set --global https://rubygems-puppetcore.puppet.com $USERNAME:$PASSWORDCopied!
  2. Specify the gem source block in the Gemfile:
    source "https://rubygems-puppetcore.puppet.com" do 
        gem 'puppet' 
    endCopied!
  3. To access the protected repository and install the gem, run the following command:
    bundle installCopied!

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.