• 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
  • Fact: puppet_status_check_role
  • Fact: puppet_status_check
  • Fact: agent_status_check
• How to report an issue or contribute to the module

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.

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.

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.

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.

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

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

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

Check basic agent status:

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

Check puppet server infrastructure status:

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

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'],
}

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 }'

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

puppet_status_check::summary utilize hiera 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

See the following documentation for further explanation.

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 puppet_status_check::summary.

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

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

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

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

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"]}'

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","AS002"]}'

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. _

This fact is confined to run on infrastructure nodes only.

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

| AS001 | Determines if the agent host certificate is expiring in the next 90 days. | Puppet Enterprise has a plan built into extend agent certificates. Use a puppet query to find expiring host certificates and pass the node ID to this plan: puppet plan run enterprise_tasks::agent_cert_regen agent=$(puppet query 'inventory[certname] { facts.agent_status_check.AS001 = false }' \| jq -r '.[].certname' \| paste -sd, -) master=$(puppet config print certname) | If the plan fails to run, open a support ticket referencing AS001 and provide the error message received when running the plan. | | AS002 | Determines if the pxp-agent has an established connection to a pxp broker | Ensure the pxp-agent service is running, if running check /var/log/puppetlabs/pxp-agent/pxp-agent.log (on *nix) or C:/ProgramData/PuppetLabs/pxp-agent/var/log/pxp-agent.log (on Windows) — Contains the for connection issues, first ensuring the agent is connecting to the proper endpoint, for example, a compiler and not the primary. This fact can also be used as a target filter for running tasks, ensuring time is not wasted sending instructions to agents not connected to a broker| If unable to make a connection to a broker, raise a ticket with the support team quoting AS002 and attaching the file /var/log/puppetlabs/pxp-agent/pxp-agent.log (on *nix) or C:/ProgramData/PuppetLabs/pxp-agent/var/log/pxp-agent.log (on Windows) along with the conclusions of your investigation so far | | AS003 | Determines the certname configuration parameter is incorrectly set outside of the [main] section of the puppet.conf file. | The Puppet documentation states clearly certname should always be placed solely in the [main] section to prevent unforseen issues with the operation of the puppet agent https://puppet.com/docs/puppet/7/configuration.html#certname | If unable to determine why the indicator is being raised. Open a ticket with the support team quoting AS003 and attaching the file puppet.conf along with the conclusions of your investigation so far . | | AS004 | Determines if the host copy of the CRL expires in the next 90 days. | If the Output of S0023 on the primary server is also false use the resolution steps in S0023. If S0023 on the Primary is True, follow this article | Open a Support ticket referencing AS004 and provide any errors you recieved in following the resolution steps |

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.