How to Install and Configure a Puppet Agent

Puppet is an open source configuration management system. With its domain-specific language, Puppet allows system administrators to perform system configuration in a declarative way. Since Puppet configurations consist of text, they can easily be versioned, which means you can easily run diffs against competing versions to understand exactly what changed.

In this post, we’ll see how to install and configure a Puppet agent on Linux. Also, we’ll cover some examples of cool tasks you can perform with Puppet after installing the agent. Let’s get started.

Puppet’s architecture follows the server-client model, although it uses a slightly different nomenclature. A client in this model is called a Puppet agent. One or more Puppet servers are installed on the server.

Agents are installed on the machines that are to be managed. Puppet works on a pull model, which means that agents periodically query the centralized server for updates. The server compiles these updates in the form of catalogs and sends them back to the agents.

Upon receiving its catalog, each node analyzes it, iterating over its resources and comparing it with the state of its actual components. When the node detects that something needs to be changed, it carries out the necessary tasks to undergo the transformation.

After the changes are applied, the agents send a report to the centralized server.

With the basics out of the way, let’s start the practical parts of the tutorial.

For this tutorial, we’ll show you how to install a Puppet agent on Ubuntu Linux. At the time of this writing, the most recent version of Ubuntu is 20.04 LTS, code-named “Focal Fossa.” 

To follow along with the tutorial, you’ll need at least two machines running Ubuntu: one for the server and at least one for the agent. I’m using two virtual machines running Ubuntu 20.04, but you can use the setup that makes the most sense to you.

You’ll be running many commands during this tutorial, so we assume you have some familiarity with working with the command line. Also, we assume you have a Puppet server already installed and running, so we won’t be covering the installation and configuration of a Puppet server during the tutorial.

With the requirements out of the way, let’s get started.

Your first step is to enable the Puppet platform repositories. That way, the necessary components for installation will become available.

First, run the following command to download the release package:

wget https://apt.puppetlabs.com/puppet6-release-focal.deb

Then, run the following command to install the release package as sudo:

sudo dpkg -i puppet6-release-focal.deb

You’ll be prompted for your password. Type it in and press Enter. 

(Here, let’s issue an important caveat. By the time you’re reading this, the URL from the command above might have changed due to a new version of Puppet or Ubuntu being released. Notice the file has in its name the first word of the code name “Focal Fossa.” If you’re reading this after either of these things have changed, please make the necessary adjustments as you follow along. With that out of the way, let’s continue.)

Then, let’s update the apt package lists:

sudo apt-get update

This might take a little bit of time. When it’s done, installing the agent is simply a matter of running the following command:

sudo apt-get install puppet-agent

At this point, you have your agent installed. But it’s not configured yet.

First of all, we have to configure host resolution. This must be done both for the server and for the agent(s).

Using your favorite text editor, open the hosts file. The following command uses vim:

sudo vim /etc/hosts

Place the following two lines at the end of the file:

[puppet master ip] puppetmaster puppet
[puppet client ip] puppetclient

For instance, let’s say the IP addresses are 192.168.2.1 and 192.168.2.2, respectively. The two lines would then look as follows:

192.168.2.1 puppetmaster puppet
192.168.2.2 puppetclient

Then, on the agent machine, open the agent configuration file using your preferred text editor. 

sudo vim /etc/puppetlabs/puppet/puppet.conf

Then, add the following lines to the file:

[main]
certname = puppetclient
server = puppet

Save and close the file.

We're almost there. But before you can test your agent, you need to sign its certificate. With the help of certificates, Puppet can check the identity of nodes. It emits these certificates when an agent sends its first request to the server; in the next iterations, the agent then uses the certificate to identify itself.

On the server node, execute the following command to list the available certificates:

sudo /opt/puppetlabs/bin/puppetserver ca list --all

Finally, execute the following command to sign all certificates:

sudo /opt/puppetlabs/bin/puppetserver ca sign --all

Your configuration is done. It’s time to finally run the agent:

sudo systemctl start puppet

While you’re at it, ensure it runs on the boot with the following:

sudo systemctl enable puppet

To check whether it’s running, execute:

sudo systemctl status puppet

Finally, you can check whether the setup is working as expected:

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

After you have a functioning Puppet setup, you’ll be able to use it to configure and manage your infrastructure. It would be out of the scope of this post to give you a detailed tutorial on that; suffice it to say that the basic blocks of Puppet configuration are classes.

In classes, we declare resources that Puppet will take care of provisioning and managing on our nodes. With that in mind, we’ll now briefly show some examples of classes that highlight what you can do with your Puppet agents.

package { 'apache2':
 ensure  => "installed"
}

With this simple declaration, we express the need for Apache to be installed on our server.

file { /path/to/some/dir:
 ensure => "directory",
 owner => "some-user",
 group => "some-user",
 mode => 644
}

With the code above, we instruct Puppet to ensure the directory at the specified path will exist, that it will belong to the specified user and group, and that it will have read and write permissions for the owner and read permissions for anyone else.

With the following bit of Puppet code, we declare that Git must be installed:

class{git:
  gui => 'absent',
  ensure => 'installed'
}

The following excerpt configures the global user and email for signing commits:

git::user{'username':
 user_name  => 'John Doe',
 user_email => 'someuser@example.com',
}

Puppet is a powerful and flexible tool for configuration management. With Puppet, you can use code to express, in a declarative way, the desired state for your servers and ensure they adhere to that.

Puppet uses the server-client architecture, and its clients are called agents. The server is the node that oversees and manages the agents, which are the machines that will be updated using the configuration you create. Agents will periodically make requests to the server in search of updates that, when found, are applied, bringing the agent to the desired state.

In this post, you’ve seen how to install and configure a Puppet agent. You’ve also briefly learned about some of the cool things you can do once you have a working Puppet setup.

Thanks for reading. Until next time!

This post was written by Carlos Schults. Carlos is a consultant and software engineer with experience in desktop, web, and mobile development. Though his primary language is C#, he has experience with a number of languages and platforms. His main interests include automated testing, version control, and code quality.