sodcalculator

10 Tech How-To

Install Puppet Ubuntu: Setup & Config Guide

Guide 10-44160 · Updated · Step by step

To install Puppet on Ubuntu, you need to install the Puppet Server on one machine and the Puppet agent on each node you want to manage, then configure the agent to connect to the server. This guide covers the steps for both components on current Ubuntu LTS releases, using the official Puppet repository.

What Puppet Is and Why You’d Use It

Puppet is a configuration management tool that lets you define the desired state of your infrastructure as code. Instead of manually running commands on each server, you write manifests (Puppet’s configuration files) that describe how packages, services, files, and users should be configured. Puppet then enforces that state automatically, which makes it much easier to manage fleets of Ubuntu servers consistently, roll out changes across hundreds of machines, and recover from configuration drift.

It’s a mature open-source project (the core is Apache 2.0 licensed) with a large ecosystem of modules for common tasks like installing Nginx, managing SSH keys, or configuring firewall rules. Puppet is often compared to Ansible, Chef, and SaltStack; the main difference is that Puppet uses a client-server model with an agent daemon running on each node, whereas Ansible is agentless and pushes changes over SSH.

Prerequisites and Planning

Before you start, decide which machine will be the Puppet server. It should be a dedicated Ubuntu server (not your laptop) with at least 2 GB of RAM and 2 CPU cores for small deployments, though the exact requirements scale with the number of nodes. The server needs a hostname that resolves to itself (the default is puppet), and all agents must be able to reach it by that name. For a lab, you can add an entry to /etc/hosts on each machine, but in production you should use DNS.

You’ll also need sudo access on all machines, and they must be able to reach the internet to download packages. The steps below assume Ubuntu 22.04 LTS or 24.04 LTS, but they should work on other recent releases with minor adjustments to the repository codename.

Installing the Puppet Server

  1. Add the official Puppet repository and its GPG key:
wget https://apt.puppetlabs.com/puppet8-release-jammy.deb
sudo dpkg -i puppet8-release-jammy.deb
sudo apt update

Replace jammy with noble if you’re on Ubuntu 24.04. The .deb package adds the repository and key automatically.

  1. Install the server package:
sudo apt install puppetserver

This installs the server and its dependencies, including a bundled Java runtime. The default memory allocation is often low for production use; you can adjust it by editing /etc/default/puppetserver and changing the JAVA_ARGS line, for example to -Xms2g -Xmx2g.

  1. Start and enable the service:
sudo systemctl start puppetserver
sudo systemctl enable puppetserver

Check that it’s running with sudo systemctl status puppetserver. The first start may take a minute because it generates certificates and initializes the CA.

Installing the Puppet Agent

On each node you want to manage (including the server itself if you want to manage it), install the agent:

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

After installation, the agent binaries are in /opt/puppetlabs/bin, which is not on the default PATH. Either add that directory to your shell profile or use the full path. For convenience, you can also run sudo /opt/puppetlabs/bin/puppet.

Next, configure the agent to connect to your server. Edit /etc/puppetlabs/puppet/puppet.conf and add or change the server setting in the [main] section:

[main]
server = puppet.example.com

Replace puppet.example.com with the hostname or IP of your Puppet server. If you’re using a self-signed certificate (the default), the agent will verify the server’s certificate against its own CA, so the server’s hostname must match what’s in the certificate (the server’s certname).

Signing Agent Certificates

When an agent first runs, it generates a certificate signing request (CSR) and sends it to the server. On the server, list pending requests:

sudo /opt/puppetlabs/bin/puppetserver ca list

Then sign each one:

sudo /opt/puppetlabs/bin/puppetserver ca sign --certname node1.example.com

If you’re sure you want to sign all pending requests, you can use --all. After signing, the agent can complete its first run. Trigger it manually on the agent:

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

This runs Puppet once in the foreground and shows you what it does. The first run will create the node’s catalog and apply any default settings. You should see Notice: Applied catalog if everything worked.

Writing and Applying Your First Manifest

Puppet’s main configuration directory on the server is /etc/puppetlabs/code/environments/production/manifests. The default site.pp file is where you define node-specific configuration. For example, to ensure the nginx package is installed on all nodes, create or edit site.pp:

node default {
  package { 'nginx':
    ensure => installed,
  }
}

Save the file, then on the agent run sudo /opt/puppetlabs/bin/puppet agent --test again. Puppet will install nginx if it’s not already present. This is the core workflow: edit manifests on the server, then trigger agent runs (or wait for the default 30-minute interval).

Common Issues and Troubleshooting

  • Agent can’t reach the server: Check DNS and firewall. The agent connects to port 8140 by default. On the server, allow it with sudo ufw allow 8140/tcp if you use UFW.
  • Certificate verification failed: The server’s hostname must match the certname in its certificate. If you changed the hostname after installation, you may need to regenerate certificates (which is invasive) or add a DNS alias.
  • Agent runs but does nothing: Make sure the node’s hostname matches a node definition in site.pp, or that you have a node default block. If the node isn’t defined, Puppet applies only the default settings.
  • Memory issues on the server: The default Java heap may be too small for many nodes. Increase JAVA_ARGS in /etc/default/puppetserver and restart.
  • Agent service not starting: Check logs at /var/log/puppetlabs/puppet/puppet.log on the agent and /var/log/puppetlabs/puppetserver/puppetserver.log on the server.

Frequently Asked Questions

Can I install Puppet on Ubuntu without the official repository?

Yes, but it’s not recommended. Ubuntu’s universe repository includes a puppet package, but it’s often older and may not be the current major version. The official Puppet repository gives you the latest releases and security updates, and the installation steps are straightforward.

What’s the difference between Puppet Enterprise and open-source Puppet?

Puppet Enterprise (PE) is a commercial product that adds a web UI, role-based access control, and support. The open-source version is free and includes the core server, agent, and command-line tools. For most small to medium deployments, open-source is sufficient; you can migrate to PE later if you need the extra features.

How do I uninstall Puppet from Ubuntu?

On the agent, run sudo apt remove puppet-agent and optionally sudo apt purge puppet-agent to remove config files. On the server, do the same with puppetserver. You may also want to remove the repository by deleting /etc/apt/sources.list.d/puppet8-release.list and the associated key.

Can I manage Windows or macOS nodes with a Puppet server on Ubuntu?

Yes. Puppet agents are available for Windows and macOS, and they can connect to a Linux server. The configuration language is the same across platforms, though some resources (like services) behave differently. You’ll need to install the appropriate agent package on each OS.

Why is my agent not picking up changes I made to site.pp?

Agents run on a schedule (default every 30 minutes). If you want to apply changes immediately, run sudo /opt/puppetlabs/bin/puppet agent --test on the agent. Also make sure you saved the file and that the server’s environment is correct (the default is production).

Is it safe to run Puppet in a production environment?

Yes, Puppet is widely used in production, but you should test changes in a staging environment first. Use version control for your manifests, and consider using Puppet’s noop mode (puppet agent --test --noop) to preview changes before applying them.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →