Puppet Status Check

• Description
• Setup
  • What this module affects
  • Setup requirements
• Usage
  • Enable infrastructure checks
  • Disable
• Reporting Options
  • Class declaration
  • Using a Puppetdb Query to report status.
  • Ad-hoc Report (Plans)
    • Setup Requirements
    • Running the plans
• Reference
  • Facts
    • puppet_status_check_role
    • puppet_status_check
• How to report an issue or contribute to the module

Description

Puppet Status Check provides a way to alert the end-user when Puppet is not in an ideal state. It uses pre-set indicators and has a simplified output that directs the end-user to the next steps for resolution.

Setup

What this module affects

This module primarily provides status indicators the fact named puppet_status_check. Once nodes have been classified with the module, facts will be generated and the optional indicators can occur. By default, fact collection is set to only check the status of the Puppet agent. Puppet infrastructure checks require additional configuration.

Setup requirements

Install the module, plug-in sync will be used to deliver the required facts for this module, to each agent node in the environment the module is installed in.

Usage

Classify nodes with puppet_status_check. Notify resources will be added to a node on each Puppet run if indicator's are reporting as false. These can be viewed in the Puppet report for each node, or queried from Puppetdb.

Enable infrastructure checks

The default fact population will not perform checks related to puppet infrastructure services such as the puppetserver, puppetdb, or postgresql. To enable the checks for Puppet servers, set the following parameter to those infrastructure node(s):

puppet_status_check::role: primary

Optionally define the path to pg_config if it is not in the standard path.

puppet_status_check::pg_config_path: /usr/pgsql-16/bin/pg_config

Disable

To completely disable the collection of puppet_status_check facts, uninstall the module or classify the module with the enabled parameter:

puppet_status_check::enabled: false

Reporting Options

Class declaration

To enable fact collection and configure notifications, classify nodes with the puppet_status_check class. Examples using site.pp:

1. Check basic agent status:

   node 'node.example.com' {
     include 'puppet_status_check'
   }
   

2. Check puppet server infrastructure status:

   node 'node.example.com' {
     class { 'puppet_status_check':
       role => 'primary',
     }
   }
   

3. For maximum coverage, report on all default indicators. However, if you need to make exceptions for your environment, classify the array parameter indicator_exclusions with a list of all the indicators you do not want to report on.

   class { 'puppet_status_check':
     indicator_exclusions => ['S0001','S0003','S0003','S0004'],
   }
   

Using a Puppetdb query to report status.

As the module uses Puppet's existing fact behavior to gather the status data from each of the agents, it is possible to use PQL (puppet query language) to gather this information.

Consult with your local Puppet administrator to construct a query suited to your organizational needs. Please find some examples of using the puppetdb_cli gem to query the status check facts below:

1. To find the complete output from all nodes listed by certname (this could be a large query based on the number of agent nodes, further filtering is advised ):

   puppet query 'facts[certname,value] { name = "puppet_status_check" }'
   

2. To find the complete output from all nodes listed by certname with the primary role:

   puppet query 'facts[certname,value] { name = "puppet_status_check" and certname in facts[certname] { name = "puppet_status_check_role" and value = "primary" } }'
   

3. To find those nodes with a specific status check set to false:

   puppet query 'inventory[certname] { facts.puppet_status_check.S0001 = false }'
   

Ad-hoc Report (Plans)

The plan puppet_status_check::summary summarizes the status of each of the checks on target nodes that have the puppet_status_check fact enabled. Sample output can be seen below:

TBC

Setup Requirements

Hiera is utilized to lookup test definitions, this requires placing a static hierarchy in your environment level hiera.yaml.

plan_hierarchy:
  - name: "Static data"
    path: "static.yaml"
    data_hash: yaml_data

Refer to the bolt hiera documentation for further explanation.

Using Static Hiera data to populate indicator_exclusions when executing plans

Place the plan_hierarchy listed in the step above, in the environment layer.

Create a [static.yaml] file in the environment layer hiera data directory

puppet_status_check::indicator_exclusions:                                             
  - '<TEST ID>'                                                                

Indicator ID's within array will be excluded when running the puppet_status_check::summary plan.

Running the plans

The puppet_status_check::summary plans can be run from the Puppet Bolt. More information on parameters of the plan can be viewed in [REFERENCE.md].

1. Example call from the command line to run puppet_status_check::summary against all infrastructure nodes:

   bolt plan run puppet_status_check::summary role=primary
   

2. Example call from the command line to run puppet_status_check::summary against all regular agent nodes:

   bolt plan run puppet_status_check:summary role=agent
   

3. Example call from the command line to run against a set of infrastructure nodes:

   bolt plan run puppet_status_check::summary targets=server-70aefa-0.region-a.domain.com,psql-70aefa-0.region-a.domain.com
   

4. Example call from the command line to exclude indicators for puppet_status_check::infra_summary:

   bolt plan run puppet_status_check::summary -p '{"indicator_exclusions": ["S0001","S0021"]}'
   

5. Example call from the command line to exclude indicators for puppet_status_check::agent_summary:

   bolt plan run puppet_status_check::summary -p '{"indicator_exclusions": ["AS001"]}'
   

Reference

Facts

puppet_status_check_role

This fact is used to determine which status checks are included on an infrastructure node. Classify the puppet_status_check module with a role parameter to change the role.

The role is agent by default.

puppet_status_check

This fact is confined to run on infrastructure nodes only.

Refer to the table below for next steps when any indicator reports a false.

As this module was derived from the Puppet Enterprise status check module, links within the Self-service steps below may reference Puppet Enterprise specific solutions. The goal over time is to eventually update these to include Open Source Puppet as well.

How to report an issue or contribute to the module

If you have a reproducible bug, you can open an issue directly in the GitHub issues page of the module. We also welcome PR contributions to improve the module. Please see further details about contributing.

Reference

Table of Contents

Classes

• puppet_status_check: puppet_status_check fact and failed indicators

Data types

• Puppet_status_check::Role: puppet status check role

Plans

• puppet_status_check::summary: Summary report if the state of status check on each node Uses the facts task to get the current status from each node and produces a summary report in JSON

Classes

puppet_status_check

When this class is included and enabled, any of the indicators in the puppet_status_check fact that are false will add a notify resource to the catalog. Individual indicators can be disabled by adding the ID to the indicator_exclusions parameter.

Examples

include 'puppet_status_check':

Parameters

The following parameters are available in the puppet_status_check class:

• enabled
• role
• indicate
• indicator_exclusions
• checks
• postgresql_service
• pg_config_path

enabled

Data type: Boolean

Enable checks

Default value: true

role

Data type: Puppet_status_check::Role

Role node performs

Default value: 'agent'

indicate

Data type: Boolean

Enable notify resources for failed checks

Default value: true

indicator_exclusions

Data type: Array[String[1]]

List of disabled indicators, place any indicator ids you do not wish to report on in this list

Default value: ['AS003', 'S0006']

checks

Data type: Hash

Hash containing a description for each check

postgresql_service

Data type: String

Name of postgresql service unit

Default value: 'postgresql'

pg_config_path

Data type: String

Path to postgresql pg_config binary

Default value: 'pg_config'

Data types

Puppet_status_check::Role

puppet status check role

Alias of Enum['primary', 'compiler', 'postgres', 'agent']

Plans

puppet_status_check::summary

Summary report if the state of status check on each node Uses the facts task to get the current status from each node and produces a summary report in JSON

Parameters

The following parameters are available in the puppet_status_check::summary plan:

• targets
• indicator_exclusions

targets

Data type: Optional[TargetSpec]

A comma seprated list of FQDN's of Puppet infrastructure agent nodes Defaults to using a PuppetDB query to identify nodes

Default value: undef

indicator_exclusions

Data type: Array[String[1]]

List of disabled indicators, place any indicator ids you do not wish to report on in this list Static Hiera Data can be used to set indicator_exclusions in a plan - for more information see https://www.puppet.com/docs/pe/latest/writing_plans_in_puppet_language_pe.html#using_hiera_with_plans

Default value: lookup('puppet_status_check::indicator_exclusions', undef, undef, [])

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v0.9.1 - 2024-05-10

Full Changelog

Fixed

• Fix broken fact generation when unable to run pg_config on primary #4 (h0tw1r3)

v0.9.0 - 2024-05-02

Full Changelog