Retrieve a Puppet last run summary

The following examples demonstrate how to use the Puppet Job API to retrieve a summary of the last Puppet run on target nodes using the last_run_summary action. The payload contains resource counts and timing information from the most recent Puppet run, including details such as total resources, changed resources, failed resources, and run duration. At scale, this action can be used to identify errors or provide insight into the general state of the target nodes. The response will indicate that the Puppet job is created and is scheduled to run. You can use the job ID from the response to retrieve the job status and payload details.

Request syntax

The target for a Puppet last_run_summary job can be specified using a list of node hostnames, a node group name, a node group ID, a saved filter name, or a saved filter ID. Only one target parameter can be used per request.

Target nodes using a list of hostnames.

post api/jobs/puppet '{"action":"last_run_summary","hostnames":["<node_hostname>"]}'

Target nodes using a node group name.

post api/jobs/puppet '{"action":"last_run_summary","node_group_name":"<node_group_name>"}'

Target nodes using a node group ID.

post api/jobs/puppet '{"action":"last_run_summary","node_group_id":<node_group_id>}'

Target nodes using a saved filter name.

post api/jobs/puppet '{"action":"last_run_summary","saved_filter_name":"<saved_filter_name>"}'

Target nodes using a saved filter ID.

post api/jobs/puppet '{"action":"last_run_summary","saved_filter_id":<saved_filter_id>}'

Payload property definitions

The following are the values that are returned when retrieving the payload of a Puppet last run summary API call.

Value	Description
`total_resources`	The total number of resources in the Puppet catalog.
`out_of_sync_resources`	The number of resources the Puppet agent detects changes on and acts upon it. This value is a sum of both successful and failed changes.
`failed_resources`	The number of resources the Puppet agent detected a change on but failed to apply the change.
`changed_resources`	The number of resources the Puppet agent detected a change on and successfully applied the change.
`corrected_resources`	The number of resources that were corrected during the Puppet run.
`skipped_resources`	The number of resources that were skipped during the Puppet run.
`total_time`	The amount of time, in seconds, that the Puppet job ran for.
`config_retrieval_time`	The amount of time, in seconds, that Puppet took to retrieve the configuration.
`since_lastrun`	The amount of time, in seconds, that has elapsed since the last Puppet run completed.

Examples

Example 1: Retrieve the last run summary for a list of hostnames.

This example starts a Puppet job to retrieve the last run summary for nodes with hostnames sit0001red0 and sit0001red1.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"last_run_summary","hostnames":["sit0001red0","sit0001red1"]}'

Response

{
    "id": 1541717,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "last_run_summary",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-04T23:20:57Z"
}

Example 2: Retrieve the last run summary using a node group name.

This example starts a Puppet job to retrieve the last run summary for all nodes in the node group Test Node Group.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"last_run_summary","node_group_name":"Test Node Group"}'

Response

{
    "id": 1541718,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "last_run_summary",
        "node_group_name": "Test Node Group"
    },
    "time_started": "2024-09-04T23:24:10Z"
}

Retrieving the payload of a Puppet last_run_summary job.

Use the following API call to retrieve the job details, which includes the payload with the last run summary for each node. Ensure that you are using the job ID from the output of the previous API call when requesting the job details.

ruby api.rb <customer_code> get api/jobs/1541717\?include_payload=true

Response

{
    "id": 1541717,
    "type": "Puppet",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0001red0": {
                "time": {
                    "total_time": "75.06993844099999 seconds",
                    "since_lastrun": "763 seconds",
                    "config_retrieval_time": "14.747973121 seconds"
                },
                "resources": {
                    "total_resources": 6355,
                    "failed_resources": 0,
                    "changed_resources": 23,
                    "skipped_resources": 0,
                    "corrected_resources": 5,
                    "out_of_sync_resources": 23
                }
            },
            "sit0001red1": {
                "time": {
                    "total_time": "102.12426932999998 seconds",
                    "since_lastrun": "1080 seconds",
                    "config_retrieval_time": "19.324146348 seconds"
                },
                "resources": {
                    "total_resources": 6331,
                    "failed_resources": 0,
                    "changed_resources": 19,
                    "skipped_resources": 0,
                    "corrected_resources": 5,
                    "out_of_sync_resources": 19
                }
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 2,
    "failed_nodes_count": 0,
    "total_nodes_count": 2,
    "parameters": {
        "action": "last_run_summary",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-04T23:20:57Z",
    "time_finished": "2024-09-04T23:20:58Z"
}