Installation and configuration of Puppet Master and Agent

Introduction

Puppet is an open-source configuration management tool that allows users to configure any number of servers in an automated way.

This means, on a main server ("Master") you can define how other servers should be set up. The settings are automatically adopted by all other servers ("Agents").

This tutorial covers the basic steps to set up a Puppet Master / Agent environment on Ubuntu 24.04. This tutorial does not cover the master / agent configuration options in their entirety, nor does it cover the Puppet modules. You can find further information here.

Prerequisites

• 2 servers with Ubuntu 24.04
  • Root access or access to a user with sudo permmissions
• Use an NTP service (time differences can lead to problems)
• Allow port 8140 in the firewall for incoming traffic (INPUT chain)

Example terminology

• Server 1:

  Hostname: puppetmaster
  This server will have Puppet Master installed.

• Server 2:

  Hostname: puppetagent
  This server will have Puppet Agent installed.

Step 1 - Setup hostname entries

Before you install Puppet, you need to setup some local hostname entries on both servers. To do this, edit this file on both servers:

sudo nano /etc/hosts

• On the server that will have Puppet Master installed

  » In the line that mentions "localhost", add "puppet".

  » Add a new line with the IP address of the server that will have Puppet Agent installed and point it to "puppetagent".

  127.0.0.1 localhost puppet
  <ip_of_agent_server> puppetagent

• On the server that will have Puppet Agent installed

  » Add a new line with the IP address of the server that will have Puppet Master installed and point it to "puppet".

  <ip_of_master_server> puppet

Step 2 - Install Puppet Master

You need to follow this step on server 1 (puppetmaster) only.

The following commands install Puppet Master, obtaining the package directly from Puppet in the latest version for Ubuntu 24.04 (noble).

wget https://apt.puppet.com/puppet-release-noble.deb
sudo dpkg -i puppet-release-noble.deb
sudo apt update
sudo apt install puppetserver 

Run puppetserver --version to check if Puppet Master was installed successfully. Next, use these commands to start the Puppetserver and to have it start automatically after a reboot. Afterwards, you should check the status to make sure it started successfully.

sudo systemctl start puppetserver
sudo systemctl enable puppetserver
sudo systemctl status puppetserver

If you are getting the following error when you start the Puppetserver:

Job for puppetserver.service failed because the control process exited with error code

This may indicate a lack of RAM. Here it can help to adjust the memory size in the Puppetserver configuration, e.g. to 1g.

sudo nano /etc/default/puppetserver
JAVA_ARGS="-Xms1g -Xmx1g -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"

If you encounter problems with the certificate, you can delete the CA and use sudo puppetserver ca setup to recreate it.

Step 3 - Install Puppet Agent

You need to follow this step on server 2 (puppetagent) only.

To install the Puppet Agent, follow a similar procedure:

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

Run puppet --version to check if Puppet Agent was installed successfully. If it was, you have to specify the Puppet Master in the Puppet Agent configuration. In this file, you can also define an interval for the Puppet runs. With the example below, the Puppet run is executed every 30 minutes (see "runinterval").

sudo nano /etc/puppet/puppet.conf

Add this content:

[main]
certname = puppetagent
server = puppet
runinterval = 30m

Again, start Puppet, enable it to start automatically on reboot and confirm the service was started successfully.

sudo systemctl start puppet
sudo systemctl enable puppet
sudo systemctl status puppet

Step 4 - Sign certificate

Now that Puppet Master and Puppet Agent are installed and configured, it's time for the communication. For this purpose, Puppet uses certificates, which must be signed by the Puppet master. By starting the Puppet Agent, a certificate request has already been sent to the Puppet Master. You can manage open certificate requests as follows:

• On puppetmaster

  View all open certificate requests:

  sudo puppetserver ca list

  Example output:

  Requested Certificates:
      puppetagent       (SHA256)  55:F3:8B:8D:E8:41:25:0D:A1:CC:0C:D9:73:98:99:6E:73:77:83:97:9D:30:98:03:14:62:3B:F8:7A:25:35:41

  In the output, you will see all requesting agents. You should only sign certificates that are known to you.

  sudo puppetserver ca sign --certname <name>

• On puppetagent

  You can check if the connection between Puppet Master and Agent is working using the following command:

  puppet ssl bootstrap

  The output should look something like this:

  Info: csr_attributes file loading from /home/holu/.puppet/etc/csr_attributes.yaml
  Info: Creating a new SSL certificate request for puppetagent
  Info: Certificate Request fingerprint (SHA256): 2F:2D:8F:94:82:F9:1B:B7:E3:C8:80:DB:99:29:B4:64:AC:BA:F9:E1:D6:79:4C:5F:26:0B:23:8A:1A:78:59:FF
  Info: Downloaded certificate for puppetagent from https://puppet:8140/puppet-ca/v1
  Notice: Completed SSL initialization

  If you get an error, such as Couldn't fetch certificate from CA server, go back to server 1 puppetmaster, view all open certificate requests and sign the certificate again, if needed.

You can now start managing your servers in an automated way via Puppet.

Step 5 - Create example file

To describe a system configuration, you need something called "manifests". This tutorial shows a simple example to demonstrate the basic function.

Connect to puppetmaster and create a new manifest:

sudo mkdir -p /etc/puppet/code/environments/production/manifests
sudo nano /etc/puppet/code/environments/production/manifests/site.pp

Add the following content:

node 'puppetagent'             {  # will be executed only for this node; use hostname
  file { '/tmp/example-hello':    # resource type and filename
    ensure => present,            # must be present
    mode => '0644',               # file permission
    content => "Hello World!\n",  # file content
  }
}

node default {} # will be executed for all nodes not mentioned explicitly

When the automated Puppet run is performed, it will create a new file on puppetagent. In "Step 3", the Puppet run was set to run every 30 minutes (runinterval = 30m). To trigger the Puppet run right away, you can run this command on puppetagent:

sudo /usr/bin/puppet agent --test

After a successful Puppet run, you should get the output "Hello World!", when you run this command on puppetagent:

cat /tmp/example-hello

Conclusion

You now have Puppet installed and are ready to experiment and use Puppet with your own manifests!

License: MIT