Create a Puppet job

POST api/jobs/puppet

Orchestrate the Puppet agent to perform a job. The response will indicate that the Puppet job is scheduled to run. You can use the job ID from the response to retrieve the job status and payload.

In order to perform this action, the following conditions must be met:

Must have the Remote Job Execution feature turned on at the site level.
The user must have the following capabilities:
- Create and Update a Puppet Run job

Request syntax

post api/jobs/puppet '{target_details}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required
`hostnames`	String array	The list of nodes on which to run the Puppet job.	Dependent. Only if no node group or saved filter is provided.
`node_group_name`	String	The name of the node group on which to run the Puppet job. The Puppet job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`node_group_id`	Integer	The ID of the node group on which to run the Puppet job. The Puppet job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`saved_filter_name`	String	The name of the saved filter on which to run the Puppet job. The Puppet job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`saved_filter_id`	Integer	The ID of the saved filter on which to run the Puppet job. The Puppet job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`action`	String	The Puppet action to start. Available options are: `status`, `enable`, `disable`, `runonce`, and `last_run_summary`.	Yes
`environment`	String	The Puppet environment to use. This parameter is specified when the `runonce` action is used.	Only if the `runonce` action is used.
`noop`	Boolean	Whether or not to run Puppet as a dry-run. If `true`, the `--noop` flag is passed to Puppet and the daemon runs in a no-op or dry-run mode. This is useful for seeing what changes Puppet will make without actually executing the changes.	No
`reason`	String	The reason to disable Puppet. This parameter is only specified when the `disable` action is used.	Only if the `disable` action is used.

Response syntax

When the hostnames request parameter is used, the following response syntax is received.

{
    "id": integer,
    "type": "Puppet",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "success_nodes_count": integer,
    "failed_nodes_count": integer,
    "total_nodes_count": integer,
    "parameters": {
        "action": "string",
        "hostnames": [
            "string",
            "string"
        ]
    },
    "payload": "string",
    "time_started": "timestamp"
}

When the node group or saved filter request parameters are used, the following response syntax is received.

{
    "id": integer,
    "type": "Puppet",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "success_nodes_count": integer,
    "failed_nodes_count": integer,
    "total_nodes_count": integer,
    "parameters": {
        "action": "string",
        "node_group_name": "string",
        "node_group_id": integer,
        "saved_filter_name": "string",
        "saved_filter_id": integer
    },
    "payload": "string",
    "time_started": "timestamp"
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`id`	Integer	The ID of the Puppet job.
`type`	String	The type of job. For Puppet jobs, it is `Puppet`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`trigged_by`	String	The username of the person who initiated the job.
`success_nodes_count`	Integer	The number of nodes that returned a successful response.
`failed_nodes_count`	Integer	The number of nodes that returned a failed response.
`total_nodes_count`	Integer	The total number of nodes the job ran on.
`parameters`	String	The request parameters indicating the hostnames, node groups, or saved filters the Puppet job ran on.
`payload`	String	The payload for the job.
`time_started`	Timestamp	The timestamp indicating when the job started. The timestamp is given in ISO 8601 UTC datetime format.

The following data is returned if you include the payload.

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

Errors

The following are common errors returned by this API. For a list of additional common errors, see Common errors.

Code	Message	Cause
400	`The job target is missing, please specify targets using the fields: hostnames, node_group_id, node_group_name, saved_filter_id or saved_filter_name.`	The request didn't include a target. Edit the request and include at least one target and try again.
400	`Please use only one target parameter`	The request included multiple target parameters. Verify the request only specifies a single target and try again.
400	`Hostnames <hostnames> does not exist.`	The request specified a hostname that doesn't exist. Verify the request and try again.
400	`The node group name <node_group_name> does not exist.`	The request specified a node group name that doesn't exist. Verify the request and try again.
400	`Node group id <node_group_id> does not exist.`	The request specified a node group ID that doesn't exist. Verify the request and try again.
400	`Filter title <filter_name> does not exist.`	The request specified a saved filter name that doesn't exist. Verify the request and try again.
400	`Filter id <filter_id> does not exist.`	The request specified a saved filter ID that doesn't exist. Verify the request and try again.
403	`Remote Job Execution feature disabled!`	The `Remote Job Execution` feature is turned off at the site level. Have an Administrator turn it on and try again.
422	`An unfinished job was found with the same type, parameters and username (id: <existent job id>).`	A similar job is already running. Wait until that job completes before starting a new job.
422	`Reason: Can't be blank.`	The `reason` parameter is required when starting a job with the `disable` action. Specify a `reason` and try again.
500	`An unexpected error happened. Please contact support!`	An unexpected error, such as an internal error occurred. Contact support.

Examples

Use the following links to view examples for each of the available Puppet Job actions.