Puppet with Foreman – PuppetDB Reporting Errors

Fixing Missing OS, Environment, and Fact Data in Foreman When Using PuppetDB

Recently, I re-introduced PuppetDB into my infrastructure to support the new confdroid_nagios module. Everything worked as expected on the Puppet side — PuppetDB stored facts, catalogs, and reports correctly.

However, when I checked Foreman, something looked wrong. All hosts showed empty fields for basic information such as Operating System, Environment, and many other facts. The core Puppet functionality was fine, but Foreman’s host overview and reporting appeared broken. After some investigation, I found a simple but important configuration mismatch.

The Root Cause

When Foreman is used as an External Node Classifier (ENC), Puppet needs a specific routing configuration to properly handle facts. This is defined in the file:

/etc/puppetlabs/puppet/routes.yaml

An older default configuration (still present in some Foreman installations) looked like this:

master:
  facts:
    terminus: puppetdb
    cache: yaml

This setup worked in earlier versions of Puppet Server, but modern Puppet Server (starting around version 7) prefers JSON for the fact cache because it is faster and avoids certain quirks of YAML.

The Correct Configuration

Update the file to use JSON as the cache format:

master:
  facts:
    terminus: puppetdb
    cache: json

After making this change, restart the relevant services:

systemctl restart puppetserver
systemctl restart foreman

As soon as the services came back up, all the missing facts — OS details, environments, custom facts, and more — started populating correctly in Foreman.

How the Pieces Fit Together

To make the interaction clearer, here’s a visual overview of the data flow between the Puppet agent, Puppet Server, PuppetDB, and Foreman:

Key flow explained:

• The Puppet agent reports facts to the Puppet Server.
• Puppet Server stores them in PuppetDB (using the puppetdb terminus).
• When Foreman acts as the ENC, the Puppet Server also needs to retrieve facts from PuppetDB to display rich host information in the Foreman UI. The routes.yaml file tells Puppet Server exactly how to read and cache those facts. Using cache: json aligns with current Puppet Server defaults and ensures Foreman receives complete, properly formatted data.

Quick Tip

If you are running a modern Puppet Server (7 or 8) with Foreman and PuppetDB, always double-check that routes.yaml uses cache: json. The older yaml setting can silently cause missing or incomplete data in Foreman without breaking Puppet itself.

This small change took only a few minutes but restored full visibility and reporting in my Foreman dashboard. Have you run into similar fact synchronization issues between PuppetDB and Foreman? What versions are you running? Feel free to share your experiences or additional tips in the comments.

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

Related posts

• Puppet with Foreman – Pilot
• Puppet with Foreman – Installation
• Puppet with Foreman – Infrastructure
• Puppet with Foreman – R10k
• Puppet with Foreman – Host registration

Author Profile

12ww1160DevOps engineer & architect

Latest entries

• blog30.03.2026Puppet with Foreman – PuppetDB Reporting Errors
• blog28.03.2026ConfDroid Puppet Modules – Fail2ban
• blog28.03.2026WordPress – Caching riddles
• blog26.03.2026Git – Verified Commits with SSH keys