Scopes endpoints

Use the scopes endpoints to retrieve information about task-targets.

A task-target 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. Use the POST /command/task_target endpoint to create task-targets.

GET /scopes/task_targets

Retrieve information about all orchestrator task-targets.

Request format

When Forming orchestrator API requests to this endpoint, the request is a basic call, such as:
GET https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets

The GET /scopes/task_targets endpoint does not support any parameters; however, as with other orchestrator API endpoints, you must provide authentication.

Tip: The GET /scopes/task_targets endpoint returns information about all known task-targets. When there are many task-targets, the response body contains lots of data. For shorter responses, you can use the GET /scopes/task_targets/<task-target-id> endpoint to query a specific task-target, if you know the task-target's ID.

Response format

A successful response is a JSON object containing an array of task-targets. The following keys are used to provide information about each task-target:
Key Definition
id The task-target's absolute URL, which includes the task-target's numerical ID.
name A stringified number identifying the task-target.
display_name The task-target's human-readable name. Multiple task-targets can have the same display name.
tasks An array of tasks that the task-target can run. Omitted if all_tasks is true.
all_tasks A Boolean indicating whether the task-target can run any tasks on designated node targets. If tasks is specified, then all_tasks is false. If tasks is omitted, then all_tasks is true.
nodes An array of certnames identifying nodes the task-target can run tasks on. It can be empty. Combines with node_groups and pql_query to form a total node pool.
node_groups An array of node group IDs identifying node groups the task-target can run tasks on. It can be empty. Combines with nodes and pql_query to form a total node pool.
pql_query A string specifying a single PQL query identifying nodes the task-target can run tasks on. Omitted if empty. Combines with nodes and node_groups to form a total node pool.
Tip: For information about how these keys are set and possible values for each key, refer to the POST /command/task_target endpoint.
For example, this response describes three task-targets:
{
 "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
      "name": "1",
      "tasks": [
        "package::install",
        "exec"
      ],
      "all_tasks": "false",
      "nodes": [
        "wss6c3w9wngpycg",
        "jjj2h5w8gpycgwn"
      ],
      "node_groups":[
        "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
        "4932bfe7-69c4-412f-b15c-ac0a7c2883f1"
      ],
      "pql_query": "nodes[certname] { catalog_environment = \"production\" }"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/2",
      "name": "2",
      "tasks": [
        "imaginary::task"
      ],
      "all_tasks": "false",
      "nodes": [
        "mynode"
      ],
      "node_groups":[
      ]
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/3",
      "name": "3",
      "all_tasks": true,
      "nodes": [
        "xxx6c3w9wngpycg",
        "bbb2h5w8gpycgwn"
      ],
      "node_groups":[
        "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
        "4932bfe7-69c4-412f-b15c-ac0a7c2883f1"
      ]
    }
  ]
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses.

GET /scopes/task_targets/<task-target-id>

Get information about a specific task-target.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer identifying a specific task-target For example, this request queries a task-target with ID 375:
https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/375
Task-target IDs are returned in responses from the POST /command/task_target and GET /scopes/task_targets endpoints.

Response format

The response is a JSON object that uses the following keys to provide details about the task-target:
Key Definition
id The task-target's absolute URL, which includes the task-target's numerical ID.
name A stringified number identifying the task-target.
display_name The task-target's human-readable name. Multiple task-targets can have the same display name.
tasks An array of tasks that the task-target can run. Omitted if all_tasks is true.
all_tasks A Boolean indicating whether the task-target can run any tasks on designated node targets. If tasks is specified, then all_tasks is false. If tasks is omitted, then all_tasks is true.
nodes An array of certnames identifying nodes the task-target can run tasks on. It can be empty. Combines with node_groups and pql_query to form a total node pool.
node_groups An array of node group IDs identifying node groups the task-target can run tasks on. It can be empty. Combines with nodes and pql_query to form a total node pool.
pql_query A string specifying a single PQL query identifying nodes the task-target can run tasks on. Omitted if empty. Combines with nodes and node_groups to form a total node pool.
Tip: For information about how these keys are set and possible values for each key, refer to the POST /command/task_target endpoint.
For example: 
{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
  "name": "1",
  "tasks": [
    "package::install",
    "exec"
  ],
  "all_tasks": "false",
  "nodes": [
    "wss6c3w9wngpycg",
    "jjj2h5w8gpycgwn"
  ],
  "node_groups":[
    "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
    "4932bfe7-69c4-412f-b15c-ac0a7c2883f1"
  ],
  "pql_query": "nodes[certname] { catalog_environment = \"production\" }"
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 404 puppetlabs.orchestrator/unknown-task-target response if the specified task-target ID doesn't match any existing task-target IDs.