POST /command/environment_plan_run

Use parameters to run a plan on specific nodes in a specific environment.

Request format

This endpoint is similar to the POST /command/plan_run endpoint. You must define nodes to run the plan on by supplying parameters in your request.

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 containing objects	Required: The parameters you want the plan to use. Use the type key to identify whether a parameter is a query or a node group.
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 runs the example_plan on nodes specified in the targets and more_targets parameters:

{
  "plan_name" : "example_plan",
  "description" : "Output 'message' on the targets contained in 'targets' and 'more targets'",
  "params": {
    "message": {
      "value": "hello"
    },
    "example_object_param": {
       "value": {
         "value": "xyz"
       }
    },
    "targets": {
      "type": "query",
      "value": "nodes[certname] { }"
    },
    "more_targets": {
      "type": "node_group",
      "value": "<UUID>"
    }
  }
}

In this example, the parameters follow the format {<PARAM_NAME>: {"value": "<PARAM_VALUE>"}}, such as {"message": {"value": "hello"}}. The orchestrator passes <PARAM_VALUE> to the plan as the parameter's value. For object parameters, such as example_object_param, the object {"value": "xyz"} is passed to the plan as the value for example_object_param.

You can use the optional type key to give the orchestrator additional information about the parameter. This tells the orchestrator how to interpret the parameter's value. It has no relationship to the parameter's type in the plan metadata. The type key accepts these values:

• query: The parameter's value in the request is interpreted as a PuppetDB query. Orchestrator executes the query and passes the resulting list of nodes to the plan as the parameter's value. For example, if the targets parameter is set to nodes[certname] { } and resolves to ["node1", "node2"], orchestrator passes ["node1", "node2"] into the plan as the parameter's value.
• node_group: The parameter's value in the request is interpreted as a node group UUID. Orchestrator fetches all the nodes in the node group and passes them to the plan as the parameter's value. For example, if the more_targets parameter is set to a specific UUID and resolves to ["node_group1", "node_group2"], orchestrator passes that array into the plan as the parameter's value.

Refer to POST /command/plan_run for curl command examples you can modify to use with this endpoint.

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"
}

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	Any of various possible validation errors, such as the plan_name not being a properly-formatted string or an error in the params.
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.