Run the Puppet agent once

The following examples demonstrate how to use the Puppet Job API to trigger a one-time Puppet agent run on target nodes using the runonce action. An optional environment parameter can be provided to specify which Puppet environment to use. An optional noop parameter can also be provided to perform a dry-run, showing what changes Puppet would make without actually applying them. 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 runonce 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":"runonce","hostnames":["<node_hostname>"]}'

Target nodes using a node group name.

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

Target nodes using a node group ID.

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

Target nodes using a saved filter name.

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

Target nodes using a saved filter ID.

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

Action-specific parameters

Parameter	Type	Description	Required
`environment`	String	The Puppet environment to use for this run. This parameter is usually omitted, but it can be used to override the default environment specified in SC//Reliant™ Platform Manager.	No
`noop`	Boolean	Whether to run Puppet in no-op (dry-run) mode. If `true`, the `--noop` flag is passed to Puppet and the daemon runs without applying any changes. This is useful for previewing what Puppet would change.	No

Examples

Example 1: Run the Puppet agent once for a list of hostnames.

This example starts a Puppet job to trigger a one-time Puppet run on node sit0001red0.

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

Response

{
    "id": 1541251,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "runonce",
        "hostnames": [
            "sit0001red0"
        ]
    },
    "time_started": "2024-09-03T19:16:04Z"
}

Example 2: Run the Puppet agent once in no-op mode using a node group name.

This example starts a Puppet job to trigger a one-time Puppet dry-run for all nodes in the node group Test Node Group. Because noop is set to true, Puppet reports what changes it would make without actually applying them.

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

Response

{
    "id": 1541252,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "noop": true,
        "action": "runonce",
        "node_group_name": "Test Node Group"
    },
    "time_started": "2024-09-03T19:18:47Z"
}

Retrieving the payload of a Puppet runonce job.

Use the following API call to retrieve the job details, which includes the payload confirming the Puppet run was initiated on 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/1541251\?include_payload=true

Response

{
    "id": 1541251,
    "type": "Puppet",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0001red0": {
                "summary": "Started a Puppet run using the 'puppet agent --onetime --no-daemonize --color=false --show_diff --verbose --splay --splaylimit 30 --no-noop' command",
                "statusmsg": "OK",
                "statuscode": 0,
                "initiated_at": 1756310512
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 1,
    "failed_nodes_count": 0,
    "total_nodes_count": 1,
    "parameters": {
        "action": "runonce",
        "hostnames": [
            "sit0001red0"
        ]
    },
    "time_started": "2025-08-27T16:01:39Z",
    "time_finished": "2025-08-27T16:01:54Z"
}