Command endpoints

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }}'

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

{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}

{
  "environment" : "",
  "enforce_environment": false,
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  },
  "userdata": {
    "servicenow_ticket": "INC0011211"
  }
}

{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}

• id: An absolute URL that links to the newly created job.
• name: A stringified number identifying the newly created job. You can use this with other endpoints, such as GET /jobs/<job-id> (retrieve information about the status of the job) and POST /command/stop.

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

{
  "job": "1234"
}

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/stop"
data='{"job": "1234"}'

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

• id: An absolute URL that links to the stopped job. This is based on the job key in the request.
• name: A stringified number identifying the stopped job.
• nodes: A hash showing all possible node statuses, and how many nodes are currently in each status.

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
    "name" : "1234",
    "nodes" : {
      "new" : 5,
      "running" : 8,
      "failed"  : 3,
      "errored" : 1,
      "skipped" : 2,
      "finished": 5
    }
  }
}

{
  "plan_job": "1234"
}

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/stop_plan"
data='{"plan_job": "1234"}'

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

{
  "name": "1234"
}

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

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"

[
  {
    "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"
  }
]

• 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.

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

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

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

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"

• 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.

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

• 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.

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

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"

{
  "name" : "1234"
}

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

• 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.

{
  "name" : "1234"
}

• Specified the content type as application/json
• Contained a JSON object body
• Included these required keys: environment, scope, scheduled_time
• Could include several optional keys.

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }, "scheduled_time": "2027-05-05T19:50:08Z"}'

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

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

• Specified the content type as application/json
• Contained a JSON object body
• Included these required keys: environment, params, scope, scheduled_time, and task
• Could include several optional keys.

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_task"
data='{"environment" : "production", "task" : "package", "params" : {}, "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }, "scheduled_time": "2027-05-05T19:50:08Z"}'

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

{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81"
    "name" : "81"
  }
}

• Specified the content type as application/json
• Contained a JSON object body
• Included these required keys: plan_name and scheduled_time
• Could include some optional keys.

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_plan"
data='{"plan_name" : "canary", "params" : { "nodes" : ["node1.example.com", "node2.example.com"]}, "scheduled_time" : "2027-05-05T19:50:08Z"}'

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

{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81",
    "name" : "81"
  }
}