Checkmk Puppet Agent Monitoring Plugin

A lightweight Checkmk local check script for monitoring the Puppet Agent status.

This plugin checks the result of the last Puppet Agent run by analyzing the official Puppet summary file:

/opt/puppetlabs/puppet/public/last_run_summary.yaml

The script is designed for Linux systems running Puppet Agent and provides monitoring of:

• Last successful Puppet run age
• Failed resources
• Failed events
• Overall Puppet execution status

---

Why this plugin was created

There are several existing Puppet monitoring plugins available in the Checkmk Exchange.

However, most of them have one or more of the following limitations:

• They require additional Puppet commands to be executed (puppet agent --test, puppet status, etc.)
• They may increase load on production servers by running Puppet-related commands during monitoring checks
• They depend on specific Puppet versions or command output formats
• They provide more information than required for basic operational monitoring

This plugin uses a different approach:

• It does not execute Puppet commands
• It does not trigger Puppet runs
• It does not require additional Puppet modules
• It only reads the already generated Puppet Agent summary file

The Puppet Agent itself creates the summary file after every run, therefore the monitoring check only consumes existing data.

This makes the check lightweight, predictable, and safe for production environments.

---

How it works

The script reads:

/opt/puppetlabs/puppet/public/last_run_summary.yaml

and extracts:

Last Puppet run timestamp

The last_run Unix timestamp is used to calculate how long ago the last Puppet run was executed.

Example:

last_run: 1753771200

Failed resources

The script checks the number of failed Puppet resources:

resources:
  failed: 0

Failed events

The script checks failed Puppet events:

events:
  failure: 0

The total failure count is calculated as:

failed resources + failed events

---

Check logic

The check returns the following states:

State	Condition
OK	Last Puppet run was within 45 minutes and no failures detected
CRITICAL	Last Puppet run is older than 45 minutes
CRITICAL	Puppet resources or events failed

---

Example output

Successful Puppet run:

0 Puppet_Agent age=1094s failures=0 OK: Last run 18m ago, no errors

Failed Puppet run:

2 Puppet_Agent age=600s failures=3 CRITICAL: Puppet run failed (resources=2, events=1)

Puppet agent stopped or scheduler problem:

2 Puppet_Agent age=3600s failures=0 CRITICAL: Last run was 60 minutes ago

---

Installation

Copy the script to the Checkmk local checks directory:

/usr/lib/check_mk_agent/local/

Example:

cp check_puppet /usr/lib/check_mk_agent/local/check_puppet

chmod +x /usr/lib/check_mk_agent/local/check_puppet

---

Testing

Run the script manually:

/usr/lib/check_mk_agent/local/check_puppet

Expected output:

0 Puppet_Agent age=300s failures=0 OK: Last run 5m ago, no errors

You can also test the Checkmk agent output:

check_mk_agent

The local check section should contain:

<<<local>>>
0 Puppet_Agent ...

---

Requirements

• Linux system
• Puppet Agent installed
• Puppet Agent summary enabled
• Checkmk Agent installed

Default Puppet summary location:

/opt/puppetlabs/puppet/public/last_run_summary.yaml

---

Configuration

The following threshold is currently hardcoded:

2700 seconds

which equals:

45 minutes

If Puppet runs more or less frequently in your environment, adjust:

if [ "$AGE" -gt 2700 ]; then

---

Files

Repository structure:

check_puppet/
├── README.md
├── check_puppet
└── CHANGELOG.md

---

License

This script is provided as-is.

Feel free to modify it according to your Checkmk and Puppet environment.