POST /command/plan_run

Use the plan executor to run a plan.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using these keys:

Key	Format	Definition
plan_name	String	Required: The name of the plan to run. Use the GET /plans endpoint to find plan names.
params	JSON object	The parameters you want the plan to use.
environment	String	The environment to load the plan from. The default is production.
description	String	A description of the job.
timeout	Integer	The maximum number of seconds allowed for the plan to run. Reaching the timeout limit cancels queued plan actions and attempts to interrupt in-progress actions. If unspecified, this key takes the value of default-plan-timeout, which is one of the Orchestrator and pe-orchestration-services parameters.
userdata	JSON object	Arbitrary key/value data supplied to the job.

For example, this body starts the canary plan on two specific nodes:

{
  "plan_name" : "canary",
  "description" : "Start the canary plan on node1 and node2",
  "params" : {
    "nodes" : ["node1.example.com", "node2.example.com"],
    "command" : "whoami",
    "canary" : 1
  }
}

A complete curl request using this body might look like:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/plan_run"
data='{"plan_name" : "canary", "description" : "Start the canary plan on node1 and node2", "params" : { "nodes" : ["node1.example.com", "node2.example.com"], "command" : "whoami", "canary" : 1}}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

If the plan starts successfully, the server returns 202 and a JSON object containing the name of the newly created plan job. For example:

{
  "name" : "1234"
}

If you need to stop this plan while it is running, use the name ID with POST /command/stop_plan.

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code	Key	Description
400	puppetlabs.orchestrator/validation-error	The plan_name is not valid. Most likely, it is not a properly-formatted string.
403	puppetlabs.orchestrator/not-permitted	This error occurs when a user does not have permission to run the plan, cannot run the plan on the specified nodes, or otherwise lacks permission to complete the request.