POST /command/task_target

Create a task-target, which is a set of tasks and nodes/node groups you can use to provide specific privilege escalation for users who would otherwise not be able to run certain tasks or run tasks on certain nodes or node groups. When you grant a user permission to use a task-target, the user can run the task(s) in the task-target on the set of nodes defined in the task-target.

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
display_name	String	Required: The task-target name. There are no uniqueness requirements.
tasks	Array of strings	Conditionally required: You must specify either tasks or all_tasks. If you want to include specific tasks in the task-target, use tasks to supply an array of relevant task names. This key can be empty. If tasks is omitted or empty, you must set all_tasks to true. This key is required if all_tasks is omitted. The endpoint does not check if the specified tasks correspond to existing tasks. This means you can create task-targets that include tasks you have not yet created, and that you must manually confirm the task names are spelled correctly.
all_tasks	Boolean	Conditionally required: You must specify either tasks or all_tasks. all_tasks indicates whether any tasks can be run on designated node targets. The default is false and expects you to define specific tasks in the tasks key. However: If tasks is omitted or empty, you must set all_tasks to true. If all_tasks is omitted, you must provide a valid tasks key. If all_tasks is true, omit tasks. If you specify tasks and set all_tasks to true, the endpoint ignores tasks and takes the all_tasks value.
nodes	Array of strings	Required: Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes. nodes must be either empty array or an array of certnames identifying specific agent nodes or agentless nodes to associate with this task-target. The endpoint does not check if the nodes certnames correspond to existing nodes. This means you can create task-targets that include individual nodes you have not yet configured, and that you must manually confirm the node certnames are specified correctly.
node_groups	Array of strings	Required: Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes. node_groups must be either an empty array or an array of node group IDs describing node groups associated with this task-target.
pql_query	String	Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes. pql_query is an optional string specifying a single PQL query to use to fetch nodes for this task-target. Query results must contain the certnames key to identify the nodes. While pql_query is optional, if you only use pql_query to define the nodes in the task-target, you must supply nodes and node_groups as empty arrays.

For example, this body creates a task target that allows users to run task_1 and task_2 on node1, node2, and all nodes a specific node group.

{
  "display_name": "task_target_example_1",
  "tasks": ["task_1", "task_2"],
  "nodes": ["node1" "node2"],
  "node_groups": ["00000000-0000-4000-8000-000000000000"]
}

This body allows users to run any task against node1 and node2.

{
  "display_name": "task_target_example_2",
  "all_tasks": "true",
  "nodes": ["node1" "node2"],
  "node_groups": []
}

A complete curl request for the command/task_target endpoint 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_target"
data='{"display_name": "task_target_example_2", "all_tasks": "true", "nodes": ["node1" "node2"], "node_groups": []}'

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

Response format

If the task-target is successfully created, the server returns a 200 response and a JSON object using these keys:

• id: An absolute URL that links to the task-target. You can use it with the GET /scopes/task_targets/<task-target-id> endpoint to retrieve information about the task-target.
• name: The task-target's unique identifier.

For example:

{
  "task_target": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
    "name": "1"
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. There are several reasons this endpoint might return a 400 puppetlabs.orchetrator/validation-error response, including:

• display_name is missing or empty.
• tasks is missing or empty when all_tasks is false or omitted.
• Task names in tasks are not supplied as strings.
• If all_tasks is defined, the value is not a Boolean.
• tasks is missing or empty and all_tasks is not true.
• Node names in nodes are not supplied as strings.
• Node group IDs in node_groups are not supplied as strings.
• The value of pql_query is not a string.

Related information

• POST /roles