Learn Puppet - Setup & Installation

#Introduction

In the previous episode 2, you understood Puppet's architecture — the agent run flow, the role of SSL certificates, and the ten main components. Now it's time to get hands-on: we'll build a Puppet lab from scratch. In this episode you'll install Puppet Server on one node, install Puppet Agent on a test node, connect them via SSL certificates, and complete a successful first agent run. By the end of the episode you'll also understand when to choose Puppet OSS and when to move to Puppet Enterprise.

#Topology and DNS Planning

Before installation, decide the identity of every node. Puppet depends heavily on consistent host names — agents find the server through a FQDN, not an IP.

For this lab we'll use:

Make sure all nodes can resolve each other's names. For a small lab, /etc/hosts entries are enough:

192.168.10.10   puppet.example.com
192.168.10.21   agent.example.com

#Install Puppet Server

Add the official Puppet repo matching your server's OS, then install puppetserver:

wget https://apt.puppetlabs.com/puppet8-release-focal.deb
sudo dpkg -i puppet8-release-focal.deb
sudo apt update
sudo apt install puppetserver -y

sudo rpm -Uvh https://yum.puppetlabs.com/puppet8-release-el-9.noarch.rpm
sudo dnf update
sudo dnf install puppetserver -y

Run and enable the Puppet Server service:

sudo systemctl enable --now puppetserver
sudo systemctl status puppetserver

#Install Puppet Agent on the Test Node

On the test node, install puppet-agent:

wget https://apt.puppetlabs.com/puppet8-release-focal.deb
sudo dpkg -i puppet8-release-focal.deb
sudo apt update
sudo apt install puppet-agent -y

sudo rpm -Uvh https://yum.puppetlabs.com/puppet8-release-el-9.noarch.rpm
sudo dnf update
sudo dnf install puppet-agent -y

The agent binaries live in /opt/puppetlabs/bin, so add it to PATH for easy use:

export PATH=/opt/puppetlabs/bin:$PATH
echo 'export PATH=/opt/puppetlabs/bin:$PATH' >> ~/.bashrc

Verify the installation on both sides:

puppet --version
puppetserver version

#Certificate Bootstrap and Approval

Now it's time to connect the agent to the server. On the test node, run the certificate bootstrap — this command creates a key, a CSR, and downloads the CA certificate from the server:

sudo /opt/puppetlabs/bin/puppet ssl bootstrap

On the server side, check the list of CSRs awaiting approval:

sudo puppetserver ca list

Then sign the agent's certificate:

sudo puppetserver ca sign --certname agent.example.com

#First Agent Run

With the certificate in place, run your first agent run manually — the -t flag is short for --test, which runs once and then stops:

sudo /opt/puppetlabs/bin/puppet agent -t

Pay attention to the output. Since no classes are applied yet, the first run will only show that the catalog is empty and there are no changes. If there are connection or certificate issues, the error will appear here — resolve them before moving on to the next episode.

Info: Using environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Evaluating configuration cache
Info: Starting catalog run
Info: Catalog compiled on puppet.example.com
Info: Applying configuration version '...'
Notice: Applied catalog in 0.02 seconds

#Puppet OSS vs Puppet Enterprise

In episodes 0 through 3 we use Puppet OSS — free, open source, and enough for learning and small infrastructure. For enterprise environments there's Puppet Enterprise (PE), currently version 2025.1.x with the LTS 2023.8 release also available. PE is free to use for up to 10 nodes.

Setting up PE 2025.1.x is quite different: you download the official installer from the Puppet site, run puppet-enterprise-installer, and answer the wizard. The result is a single server that already contains Puppet Server, PuppetDB, the web console, and RBAC all at once. Agent installation on target nodes is the same as OSS, and all nodes appear in the console to be managed through the classifier.

wget <pe-2025.1.x-download-url>
sudo tar -xzf puppet-enterprise-2025.1.x-<arch>.tar.gz
cd puppet-enterprise-2025.1.x-<arch>
sudo ./puppet-enterprise-installer

#Conclusion

In this episode 3 you successfully built your first Puppet lab: adding the official repos, installing Puppet Server on one node and Puppet Agent on a test node, configuring name resolution, bootstrapping SSL certificates, signing the CSR, and completing the first agent run with puppet agent -t.

Key takeaways:

• Consistent DNS is a prerequisite — agents find the server through a FQDN, not an IP.
• The trust flow: SSL bootstrap → CSR approval → agent run.
• puppet ssl bootstrap prepares the key and certificate; puppetserver ca sign approves them.
• The agent runs automatically every 30 minutes, with puppet agent -t for manual runs.
• PE adds a console, RBAC, and compliance on top of OSS — free for up to 10 nodes.

In the next episode, episode 4, we'll dive into the heart of writing configuration: manifests & resource types — learning the package, service, file, exec, user, group, and cron resources, understanding the concepts of title, parameters, and properties, and testing manifests locally with puppet apply. Time to write your first Puppet code!