DEV Community

12ww1160
12ww1160

Posted on • Edited on • Originally published at confdroid.com

Puppet with Foreman - Host Registration

#automation #devops #puppet #foreman

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:

  1. Add the Puppet 8 repository 
sudo dnf install -y https://yum.puppet.com/puppet8-release-el-9.noarch.rpm
Enter fullscreen mode Exit fullscreen mode
  1. Install the Puppet agent package 
sudo dnf install -y puppet-agent
Enter fullscreen mode Exit fullscreen mode
  1. Refresh your shell session (so the puppet command is immediately available) 
exec bash -l
Enter fullscreen mode Exit fullscreen mode

Alternatively, reboot the host if preferred.

  1. 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
Enter fullscreen mode Exit fullscreen mode

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.

  1. run the agent for the first time 
sudo puppet agent --test
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Sign the specific one:

sudo puppetserver ca sign --cert client001.example.net
Enter fullscreen mode Exit fullscreen mode

Output

Successfully signed certificate request for client001.example.net
Enter fullscreen mode Exit fullscreen mode

Back on the agent, re-run:Bash

sudo puppet agent -t
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Working with VM Templates (Golden Images)

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

  1. Install a base Rocky 9 VM.
  2. 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).
  3. 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.

Hetzner Referral

Substack

ConfDroid Feedback Portal

Related posts

Top comments (0)