POST /command/task

Run a task on a set of nodes. The task does not run on any nodes in the defined scope that you do not have permission to run tasks on.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using keys described in the following table. Most keys are required, some keys are optional, and some required keys can be empty.

Key	Format	Definition
`environment`	String	Required: The name of the environment to load the task from. The default is `production`.
`scope`	JSON object	Required: Contains exactly one key defining the nodes to run the task on: `nodes`: An array of node names to target. `query`: A PuppetDB or PQL query to use to discover nodes. The target is built from `certname` values collected at the top level of the query. `node_group`: The ID of a classifier node group that has defined rules. The node group itself must have defined rules – It is not sufficient for only the node group's parent groups to define rules. The user submitting the request must also have permissions to view the specified node group. The task does not run on any nodes specified in the scope that the user does not have permission to run the task on.
`description`	String	A optional description of the job.
`noop`	Boolean	Whether to run the job in no-op mode. The default is `false`.
`params`	JSON object	Required: Parameters to pass to the task. Can be an empty object.
`targets`	Array of JSON objects	Required: A collection of keys used to run the task on nodes through SSH or WinRM via Bolt server, such as user account information, `run-as` specifications, or a designated temporary directory. Refer to the Targets section, below, for information about optional and required keys to use in `targets`.
`task`	String	Required: The task to run on the target nodes. Use the GET /tasks endpoint to get task names.
`timeout`	Integer	The maximum number of seconds a task can take to execute on any individual node. Task execution on a node is forcibly ended if the timeout limit is reached. If unspecified, this key takes the value of `default-task-node-timeout`, which is one of the Orchestrator and pe-orchestration-services parameters.
`userdata`	JSON object	Optional arbitrary key/value data supplied to the job.

For example, this body runs the package task on the node1.example.com node in the test-env-1 environment. It passes action and name parameters to the task.

{
  "environment" : "test-env-1",
  "task" : "package",
  "params" : {
    "action" : "install",
    "name" : "httpd"
  },
  "scope" : {
    "nodes" : ["node1.example.com"]
  }
}

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/task"
data='{"environment": "test-env-1", "task" : "package", "params" : { "action": "install", "name" : "httpd" }, "scope" : { "nodes" : ["node1.example.com"] }}'

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

For additional scope examples, refer to the POST /command/deploy request format examples.

Targets

The targets key contains an array of JSON objects, where each object contains the following keys:

Key	Format	Definition
`hostnames`	Array	Required: An array of hostnames sharing the same target attributes. Each hostname must match an entry in the tasks' node list `scope`.
`user`	String	Required: Specify the user on the remote system to use to run the task.
`transport`	String	Required: Specify `ssh` or `winrm`.
`password`	String	Conditionally required: Specify the password associated with the `user` key. You must specify either this key or `private-key-content`.
`private-key-content`	String	Conditionally required: Specify the content of the SSH key used to ssh to the remote node to run on. You must specify either this key or `password`.
`port`	Integer	Specifies the port, on the remote node, to use to connect.
`run-as`	String	When using SSH, specify an optional user to use to run commands.
`sudo-password`	String	If you specify `run-as`, specify a password to use when changing users.
`run-as-command`	String	If you specify `run-as`, specify a command to use to elevate permissions.
`connect-timeout`	Integer	How long, in seconds, you want Bolt to wait when establishing connections.
`tty`	Boolean	Whether Bolt uses pseudo tty to meet sudoer restrictions.
`tmpdir`	String	Specify the directory the task can use to upload and execute temporary files on the target.
`extensions`	String	A list of file extensions that are accepted for scripts or tasks.

For example, this target array contains two JSON objects:

[
  {
    "hostnames": ["sshnode1.example.com", "sshnode2.example.com"],
    "private-key-content": "<SSH_KEY>",
    "port": 4444,
    "user": "<USER_NAME>",
    "transport": "ssh"
  },
  {
    "hostnames": ["winrmnode.example.com"],
    "password": "<PASSWORD>",
    "port": 4444,
    "user": "<USER_NAME>",
    "transport": "winrm"
  }
]

Response format

If the task starts successfully, the server returns 202 and a JSON object using these keys:

id: An absolute URL that links to the newly created job. You can use it with the GET /jobs/<job-id> endpoint to retrieve information about the status of the job.
name: A stringified number identifying the newly created job.

For example:

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
    "name" : "81"
  }
}

Error responses

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

Response code	Value	Definition
404	`puppetlabs.orchestrator/unknown-environment`	The specified `environment` does not exist.
400	`puppetlabs.orchestrator/empty-target`	There is a problem with the `target` entry in the request body, such as the `hostnames`do not match nodes defined by the `scope`.
400	`puppetlabs.orchestrator/puppetdb-error`	If the request specified a `query` for the `scope`, the orchestrator is unable to make a query to PuppetDB.
400	`puppetlabs.orchestrator/query-error`	If the request specified a `query` for the `scope`, the query is invalid or the user submitting the request does not have permission to run the query.
403	`puppetlabs.orchestrator/not-permitted`	This error occurs when a user does not have permission to run the task on the requested nodes.