Command endpoints
Sections
Use the command
endpoints to run Puppet, jobs, and plans on demand; stop
in-progress jobs; or schedule future runs of Puppet,
jobs, or plans. You can also create task-targets, which provide privilege escalation
for users who would otherwise not be able to run certain tasks or run tasks on
certain nodes or node groups.
- POST /command/deploy: Run Puppet on demand.
- POST /command/schedule_deploy: Schedule a Puppet run on a set of nodes.
- POST /command/stop: Stop an orchestrator job that is currently running.
- POST /command/task: Run a task on a set of nodes.
- POST /command/task_target: Define a set of tasks and nodes/node groups you can use to escalate privileges for users who would otherwise not be able to run those tasks or run tasks on those nodes or node groups.
- POST /command/schedule_task: Schedule a task to run in the future.
- POST /command/plan_run: Run a plan.
- POST /command/schedule_plan: Schedule a plan to run in the future.
- POST /command/environment_plan_run: Run a plan in a specified environment.
POST /command/deploy
Run Puppet on demand – run the orchestrator across all nodes in an environment.
Request format
application/json
. The body must be a JSON object
using keys described in the following table. The environment
key is always required. Additional keys might be required depending on the values of other keys.Key | Format | Definition |
---|---|---|
environment |
String |
Required: The name of the environment to deploy or an
empty string. If you supply an empty string, you must set enforce_environment to false . |
scope |
JSON object | Contains exactly one key defining the deployment target:
Required if |
concurrency |
Integer or range | The maximum number of nodes to run at one time. The default is
a range between 1 and the value of the global_concurrent_compiles parameter.For information about |
debug |
Boolean | Whether to use the --debug flag on Puppet agent runs. |
description |
String | A description of the job. |
enforce_environment |
Boolean | Whether to force agents to run in the same environment where
their assigned applications are defined. This key must be false if environment is an empty
string. |
evaltrace |
Boolean | Whether to use the --evaltrace flag on Puppet agent runs. |
filetimeout |
Integer | The value for the --filetimeout flag on Puppet agent runs. |
http_connect_timeout |
Integer | The value for the --http_connect_timeout flag
on Puppet agent runs. |
http_keepalive_timeout |
Integer | The value for the --http_keepalive_timeout
flag on Puppet agent runs. |
http_read_timeout |
Integer | The value for the --http_read_timeout flag on
Puppet agent runs. |
noop |
Boolean | Whether to run the agent in no-op mode. The default is
false . |
no_noop |
Boolean | Whether to run the agent in enforcement mode. The default is
false . This flag overrides noop = true if set
in the agent's puppet.conf file. This flag can't be set to
true if the noop
flag is also set to true . |
ordering |
String | Sets the --ordering flag on Puppet agent runs. |
skip_tags |
String | Sets the --skip_tags flag on Puppet agent runs. |
tags |
String | Sets the --tags flag on Puppet agent runs. |
trace |
Boolean | Whether to use the --trace flag on Puppet agent runs. |
use_cached_catalog |
Boolean | Whether to use the --use_cached_catalog flag
on Puppet agent runs. |
usecacheonfailure |
Boolean | Whether to use the --usecacheonfailure flag
on Puppet agent runs. |
userdata |
JSON object | Arbitrary key/value data supplied to the job. |
/command/deploy
endpoint. This request targets nodes in the All Nodes
node group in the production
environment: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"
Copied!
The following are additional examples of valid JSON bodies for the /command/deploy
endpoint.
production
environment:{
"environment" : "production",
"scope" : {
"application" : "Wordpress_app[demo]"
}
}
Copied!
production
environment:{
"environment" : "production",
"scope" : {
"nodes" : ["node1.example.com", "node2.example.com"]
}
}
Copied!
node1.example.com
node in no-op
mode:{
"environment" : "",
"enforce_environment": false,
"noop" : true,
"scope" : {
"nodes" : ["node1.example.com"]
},
"userdata": {
"servicenow_ticket": "INC0011211"
}
}
Copied!
production
environment
with a certname
value matching a
regex:{
"environment" : "production",
"scope" : {
"query" : ["from", "nodes", ["~", "certname", ".*"]]
}
}
Copied!
Response format
-
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
: The name of the newly created job.
{
"job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
"name" : "81"
}
}
Copied!
Error responses
kind
key:Response code | Value | Definition |
---|---|---|
404 | puppetlabs.orchestrator/unknown-environment |
The specified environment does
not exist. |
400 | puppetlabs.orchestrator/empty-environment |
The specified environment
contains no applications or no nodes. |
400 | puppetlabs.orchestrator/empty-target |
If the request specified an application for the scope , the
specified application instance does not exist or is empty. |
400 | puppetlabs.orchestrator/dependency-cycle |
If the request specified an application for the scope , the
application code contains a cycle. |
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. |
POST /command/schedule_deploy
Schedule a Puppet run on a set of nodes.
Request format
application/json
. The body must be a
JSON object using these required keys: Key | Definition |
---|---|
environment |
A string specifying the name of the environment to deploy or
an empty string. If you supply an empty string, you must set
enforce_environment to
false . |
scope |
A JSON object containing exactly one key defining the
deployment target:
|
scheduled_time |
A timestamp, in ISO-8601 format, defining the time to run the scheduled job. |
Key | Definition |
---|---|
concurrency |
An integer specifying the maximum number of nodes to run at one time. The default, if unspecified, is unlimited. |
debug |
A Boolean specifying whether to use the
--debug flag on Puppet agent runs. |
description |
A string describing the job. |
enforce_environment |
A Boolean specifying whether to force agents to run in the
same environment where their assigned applications are defined.
This key must be false if
environment is an empty
string. |
evaltrace |
A Boolean specifying whether to use the
--evaltrace flag on Puppet agent runs. |
filetimeout |
An integer specifying the value of the
--filetimeout flag on Puppet agent runs. |
http_connect_timeout |
An integer specifying the value for the
--http_connect_timeout flag on Puppet agent runs. |
http_keepalive_timeout |
An integer specifying the value for the
--http_keepalive_timeout flag on Puppet agent runs. |
http_read_timeout |
An integer specifying the value for the
--http_read_timeout flag on Puppet agent runs. |
interval
|
A JSON object containing units and value to
define intervals for the deployment. This object resides inside
schedule_options . |
noop |
A Boolean specifying whether to run the agent in no-op mode.
The default is false . |
no_noop |
A Boolean specifying whether to run the agent in enforcement
mode. The default is false . This flag overrides
noop = true if set in the agent's
puppet.conf file. This flag can't be set to
true if the noop flag is also set to true . |
ordering |
A string defining the value of the
--ordering flag on Puppet agent runs. |
schedule_options |
A JSON object containing the interval JSON object. Defines intervals for the
deployment. |
skip_tags |
A string defining the value of the
--skip_tags flag on Puppet agent runs. |
tags |
A string defining the value of the --tags
flag on Puppet agent
runs. |
trace |
A Boolean specifying whether to use the
--trace flag on Puppet agent runs. |
units |
Used with interval and
schedule_options . It is a
string specifying enum as seconds . |
use_cached_catalog |
A Boolean specifying whether to use the
--use_cached_catalog flag on Puppet agent runs. |
usecacheonfailure |
A Boolean specifying whether to use the
--usecacheonfailure flag on Puppet agent runs. |
value |
Used with interval and
schedule_options . It is a
positive integer specifying the amount of seconds per interval . |
/command/schedule_deploy
endpoint. This request schedules a deployment
targeting nodes in the All Nodes
node group in the
production
environment: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"
Copied!
node1.example.com
node in noop
mode:{
"environment" : "",
"enforce_environment": false,
"noop" : true,
"scope" : {
"nodes" : ["node1.example.com"]
},
"scheduled_time": "2027-05-05T19:50:08Z",
"schedule_options": {
"interval": {
"units": "seconds",
"value": 86400
}
}
}
Copied!
For additional scope
examples, refer to the POST /command/deploy request format examples.
Response format
-
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
: The name of the newly created job.
{
"job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
"name" : "81"
}
}
Copied!
Error responses
kind
key:Response code | Value | Definition |
---|---|---|
404 | puppetlabs.orchestrator/unknown-environment |
The specified environment does not exist. |
400 | puppetlabs.orchestrator/empty-environment |
The specified environment contains no applications or no
nodes. |
400 | puppetlabs.orchestrator/empty-target |
If the request specified an application for the scope , the specified application
instance does not exist or is empty. |
400 | puppetlabs.orchestrator/dependency-cycle |
If the request specified an application for the scope , the application code contains
a cycle. |
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. |
400 | puppetlabs.orchestrator/invalid-time |
The supplied scheduled_time timestamp is in the past. |
POST /command/stop
Stop an orchestrator job that is currently in progress. Any in-progress Puppet agent runs finish, but no new agent runs start. While agents are finishing, the server continues to produce events for the job.
Request format
application/json
. The body must be a JSON object
containing the job
key, which specifies to job ID of the job
to stop, such as:{
"job": "1234"
}
Copied!
You can get job IDs from the POST /command/deploy or GET /jobs responses.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"
Copied!
POST /command/stop
is idempotent – you can use it
against the same job any number of times.
Response format
202
response and
a JSON object containing these keys:-
id
: An absolute URL that links to the stopped job. This is based on thejob
key in the request. -
name
: The name of 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
}
}
}
Copied!
stopped
status when all in-progress agent runs have
finished.Error responses
kind
key:Response code | Key | Definition |
---|---|---|
400 |
puppetlabs.orchestrator/validation-error
|
The specified job ID is not formatted correctly or is otherwise not valid. |
404 |
puppetlabs.orchestrator/unknown-job
|
The specified job ID does not exist. |
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:
application scopes are not allowed for
task jobs. |
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. |
userdata
|
JSON object | Optional arbitrary key/value data supplied to the job. |
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"]
}
}
Copied!
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"
Copied!
For additional scope
examples, refer to the POST /command/deploy request format examples.
Targets
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. |
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"
}
]
Copied!
Response format
-
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
: The name of the newly created job.
{
"job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
"name" : "81"
}
}
Copied!
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. |
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.
POST
/command/task_target
endpoint to create a task-target, you must use the
POST /roles endpoint to create a role
controlling the permission to use the task-target. For an overview of the
task-target workflow, read about Puppet Enterprise RBAC API,
or how to manage access to tasks on the Puppet blog.Request format
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
Important: 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:
|
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.
Important: 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.
|
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.
Important: 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. |
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"]
}
Copied!
node1
and node2
.{
"display_name": "task_target_example_2",
"all_tasks": "true",
"nodes": ["node1" "node2"],
"node_groups": []
}
Copied!
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"
Copied!
Response format
-
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"
}
}
Copied!
Error responses
-
display_name
is missing or empty. -
tasks
is missing or empty whenall_tasks
isfalse
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 andall_tasks
is nottrue
. - 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.
POST /command/schedule_task
Schedule a task to run at a future date and time.
Request format
application/json
. The body must be a JSON object
using these keys:Key | Format | Definition |
---|---|---|
description
|
String | A description of the job. |
environment
|
String |
Required: The name of the environment to load the task from. The
default is production . |
interval
|
JSON object | Contains units and value to define intervals for running the task. This object resides
inside schedule_options . |
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. |
schedule_options |
JSON object | Contains the interval JSON object and defines
intervals for running the task. |
scheduled_time
|
Timestamp | Required: A timestamp, in ISO-8601 format, defining the time to run the scheduled job. |
scope
|
JSON object |
Required: Contains exactly one key defining the nodes to run the task on:
application scopes are not allowed for
task jobs. |
task
|
String | Required: The task to run on the target nodes. |
units |
String | Used with interval and schedule_options . Specifies enum as seconds . |
value |
Integer | Used with interval and schedule_options . It is a positive integer specifying the amount of
seconds per interval . |
package
task
on the node1.example.com
node in the test-env-1
environment. It passes the action
and
package
parameters to the
task.{
"environment": "test-env-1",
"task": "package",
"params": {
"action": "install",
"package": "httpd"
},
"scope": {
"nodes": [
"node1.example.com"
]
},
"scheduled_time": "2027-05-05T19:50:08Z",
"schedule_options": {
"interval": {
"units": "seconds",
"value": 86400
}
}
}
Copied!
/command/schedule_task
endpoint. This request schedules the package
task to run on nodes in the All
Nodes
node group in the production
environment
and passes no parameters to the
task: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"
Copied!
For additional scope
examples, refer to the POST /command/deploy request format examples.
Response format
-
id
: An absolute URL that links to the newly created job. You can use it with the DELETE /scheduled_jobs/<job-id> endpoint to delete the scheduled job. -
name
: The name of the newly created job.
{
"scheduled_job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81"
"name" : "81"
}
}
Copied!
Error responses
This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400
puppetlabs.orchestrator/invalid-time response if the scheduled_time
timestamp is in the past.
For other error codes this endpoint might return, refer to the POST /command/task error responses.
POST /command/plan_run
Use the plan executor to run a plan.
Request format
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.
Tip: Use the GET /plans endpoint to find plan
names.
|
params |
JSON object | The parameters you want the plan to use. |
environment |
String | The environment to load the plan from. The default is
production . |
description |
String | A description of the job. |
userdata
|
JSON object | Arbitrary key/value data supplied to the job. |
canary
plan on two specific
nodes:{
"plan_name" : "canary",
"description" : "Start the canary plan on node1 and node2",
"params" : {
"nodes" : ["node1.example.com", "node2.example.com"],
"command" : "whoami",
"canary" : 1
}
}
Copied!
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/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"
Copied!
Response format
name
of the newly created plan job. For
example:{
"name" : "1234"
}
Copied!
Error responses
kind
key:Response code | Key | Description |
---|---|---|
400 | puppetlabs.orchestrator/validation-error |
The plan_name is not valid. Most likely, it
is not a properly-formatted string. |
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. |
POST /command/schedule_plan
Schedule a plan to run at a later time.
Request format
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. |
scheduled_time |
Timestamp | Required: A timestamp, in ISO-8601 format, defining the time to run the scheduled plan. |
params |
JSON object | The parameters you want the plan to use. |
environment |
String | The environment to load the plan from. The default is
production . |
description |
String | A description of the job. |
userdata
|
JSON object | Arbitrary key/value data supplied to the job. |
canary
plan to run on two
specific nodes:{
"plan_name" : "canary",
"params" : {
"nodes" : ["node1.example.com", "node2.example.com"],
},
"scheduled_time": "2027-05-05T19:50:08Z"
}
Copied!
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/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"
Copied!
Response format
-
id
: An absolute URL that links to the newly created plan job. You can use it with the GET /plan_jobs/<job-id> to get information about the status of the plan job. -
name
: The name of the newly created plan job.
{
"scheduled_job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81",
"name" : "81"
}
}
Copied!
Error responses
This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a
400 puppetlabs.orchestrator/invalid-time response if the scheduled_time
timestamp is in the past.
For other error codes this endpoint might return, refer to the POST /command/plan_run error responses.
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.
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.
Tip: 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. |
userdata |
JSON object | Arbitrary key/value data supplied to the job. |
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>"
}
}
}
Copied!
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
.
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 thetargets
parameter is set tonodes[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 themore_targets
parameter is set to a specificUUID
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
name
of the newly created plan
job. For example:{
"name" : "1234"
}
Copied!
Error responses
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. |