Retrieve Puppet agent status

The following examples demonstrate how to use the Puppet Job API to request the status of the Puppet agent on target nodes using the status action. 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 status 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":"status","hostnames":["<node_hostname>"]}'

Target nodes using a node group name.

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

Target nodes using a node group ID.

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

Target nodes using a saved filter name.

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

Target nodes using a saved filter ID.

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

Examples

Example 1: Retrieve Puppet agent status for a list of hostnames.

This example starts a Puppet job requesting the status of the Puppet agent for nodes with hostnames sit0001red0 and sit0001red1.

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

Response

{
    "id": 1541246,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-03T18:47:57Z"
}

Example 2: Retrieve Puppet agent status using a node group name.

This example starts a Puppet job requesting the status of the Puppet agent for all nodes in the node group Test Node Group.

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

Response

{
    "id": 1541247,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "node_group_name": "Test Node Group"
    },
    "time_started": "2024-09-03T18:52:17Z"
}

Example 3: Retrieve Puppet agent status using a node group ID.

This example starts a Puppet job requesting the status of the Puppet agent for all nodes in node group ID 42.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"status","node_group_id":42}'

Response

{
    "id": 1541248,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "node_group_id": 42
    },
    "time_started": "2024-09-03T18:55:04Z"
}

Example 4: Retrieve Puppet agent status using a saved filter name.

This example starts a Puppet job requesting the status of the Puppet agent for all nodes that match the saved filter Test Saved Filter.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"status","saved_filter_name":"Test Saved Filter"}'

Response

{
    "id": 1541249,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "saved_filter_name": "Test Saved Filter"
    },
    "time_started": "2024-09-03T18:57:31Z"
}

Example 5: Retrieve Puppet agent status using a saved filter ID.

This example starts a Puppet job requesting the status of the Puppet agent for all nodes that match saved filter ID 17.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"status","saved_filter_id":17}'

Response

{
    "id": 1541250,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "saved_filter_id": 17
    },
    "time_started": "2024-09-03T19:00:18Z"
}

Retrieving the payload of a Puppet status job.

Use the following API call to retrieve the job details, which includes the payload with the Puppet agent status 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/1541246\?include_payload=true

Response

{
    "id": 1541246,
    "type": "Puppet",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0001red0": {
                "status": "Currently stopped; last completed run 18 minutes 09 seconds ago"
            },
            "sit0001red1": {
                "status": "Currently running; last completed run 2 hours 05 minutes 44 seconds ago"
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 2,
    "failed_nodes_count": 0,
    "total_nodes_count": 2,
    "parameters": {
        "action": "status",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-03T18:47:57Z",
    "time_finished": "2024-09-03T18:48:02Z"
}