Puppet with Foreman - Host Registration

Next Steps: Registering Puppet Agents with Foreman – The Simple, Secure Way

In the previous post, we walked through installing a fresh Puppet 8 server integrated with Foreman 3.17 (or later) on an Enterprise Linux 9 system. (For a refresher on those steps, see: Installing Puppet with Foreman.) Now comes the fun part: getting client machines (agents) to connect, register themselves, and start receiving configurations. While Foreman includes a dedicated “Register Host” section in the UI—complete with pre-filled organization, location, host group, operating system, and a generated bootstrap command—this manual approach is rarely needed in practice. The better, more scalable method is to simply install and configure the Puppet agent on the target host. Once running, the agent automatically contacts the Puppet server (your Foreman-integrated setup), submits a certificate signing request (CSR), reports facts, and appears in the Foreman UI. From there, you assign it to the appropriate organization, location, host group, and environment. This post focuses on the cleanest workflow: a fresh Rocky Linux 9 installation, followed by agent setup. We’ll also touch on virtual machine templates, certificate signing options, and how the confdroid_puppet module streamlines things further.

Option 1: Manual Agent Installation on a Fresh Rocky Linux 9 Host

Start with a vanilla Rocky Linux 9 VM or physical server (minimal install is fine). SSH in as root or a sudo user, make sure the host has a proper FQDN like client001.example.net, then run these commands:

Add the Puppet 8 repository

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

Install the Puppet agent package

sudo dnf install -y puppet-agent

Refresh your shell session (so the puppet command is immediately available)

exec bash -l

Alternatively, reboot the host if preferred.

Configure the Puppet agent

Edit /etc/puppetlabs/puppet/puppet.conf and add (or update) the [agent] section to point to your Puppet server:

[agent]
server = puppet.example.net          # Replace with your actual Foreman/Puppet server FQDN

As a matter of fact, simply adding the one-liner “server = puppet.example.net” is sufficient at this stage.

that’s it for basic setup—no other changes are typically required at this stage.

run the agent for the first time

sudo puppet agent --test

puppet agent -t is sufficient too.

This triggers:

Generation of the agent’s SSL keypair and CSR
Submission of the CSR to the Puppet server
Sending of facts about the host (OS, hardware, etc.)

If the certificate isn’t yet signed, you’ll see a message like:

Exiting; no certificate found and waitforcert is disabled

Head over to the Puppet server (or use Foreman) to sign it (more on this below).

Certificate Signing: Manual (Recommended) vs. Auto-Sign

After the first agent run, a pending certificate request appears.

Manual signing (secure default)

On the Puppet server, list pending requests:

sudo puppetserver ca list

Sign the specific one:

sudo puppetserver ca sign --cert client001.example.net

Output

Successfully signed certificate request for client001.example.net

Back on the agent, re-run:Bash

sudo puppet agent -t

The agent now retrieves its signed certificate, fetches a catalog, applies it (if classes are assigned), and reports back to Foreman.

Auto-sign (convenient but less secure)

In small/trusted labs, you can enable autosigning in /etc/puppetlabs/puppet/autosign.conf or via Foreman settings. However, this allows any host to register without verification—avoid in production environments where security matters. Accidentally assigned hosts can and will receive secrets and confident configration details. Manual or policy-based signing is strongly preferred.

Once signed and the agent runs successfully, the host automatically appears in Foreman under Hosts > All Hosts, complete with imported facts.

Bonus: Using the confdroid_puppet Module for Smarter Agent Setup

If you’re already publishing or consuming modules from the ConfDroid Forge, include the confdroid_puppet module (available at:https://sourcecode.confdroid.com/confdroid/confdroid_puppet).

This module is designed for Puppet 8 on Rocky 9 and shines in Foreman-managed environments:

On the first run, it rewrites /etc/puppetlabs/puppet/puppet.conf based on parameters passed via Foreman (e.g., setting the correct server, environment, runinterval, and more).
It disables unnecessary defaults, enables pluginsync and reporting, and applies secure, opinionated settings.

Example output after the module configures the file:

[agent]
  server                  = puppet.example.net
  classfile               = $statedir/classes.txt
  default_schedules       = false
  environment             = production
  masterport              = 8140
  noop                    = false
  pluginsync              = true
  report                  = true
  runinterval             = 1800
  splay                   = false
  splaylimit              = 1800
  usecacheonfailure       = true
  certificate_revocation  = false

Working with VM Templates (Golden Images)

In virtualized environments, speed things up by creating a template:

Install a base Rocky 9 VM.
Perform the agent installation and basic puppet.conf setup as above. 3.Clean up any unique identifiers (remove /etc/puppetlabs/puppet/ssl/* to force new cert generation on clone).
Shut down and convert to a template.

When you deploy new VMs from this template:

Boot → agent starts (via systemd) → contacts the server → requests signing → registers in Foreman.

No manual intervention needed beyond certificate approval.

Final Touches in Foreman

Once the host shows up:

Assign it to an Organization and Location (if not auto-set).
Select a Host Group (which can predefine environment, Puppet classes, parameters, etc.).
Choose the Environment (production, staging, etc.). Environments can be inherited from hostgroups.

From that point forward, Puppet modules (including those from the ConfDroid Forge) take over, applying configurations automatically on each agent run (default every 30 minutes). This workflow keeps things simple, secure, and scalable—exactly what Foreman + Puppet excels at. Next up in the series: assigning classes via Foreman, using host groups effectively, and integrating the first ConfDroid module. Stay tuned! Questions or feedback? Drop them at https://feedback.confdroid.com. Happy provisioning! 🚀

Did you find this post helpful? You can support me.