Command endpoints
Sections
Use the /command
endpoint to start and stop orchestrator jobs for tasks
and plans.
POST /command/deploy
Run the orchestrator across all nodes in an environment.
Request format
The request body must be a JSON object using these keys:
Key | Definition |
---|---|
environment
|
The environment to deploy. This key is required. |
scope
|
Object, required unless target
is specified. The PuppetDB query, a list of nodes, or a classifier node group id to
deploy. |
description
|
String, a description of the job. |
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. Defaults
to false . This flag overrides noop = true if set
in the agent's puppet.conf , and cannot be set to true at the same
time as the noop flag. |
concurrency
|
The maximum number of nodes to run at one time. The default is
the range between 1 and up to the value set by the following parameter, which
defaults to 8 : puppet_enterprise::profile::orchestrator::global_concurrent_compiles
|
enforce_environment
|
Boolean, whether to force agents to run in the same environment
in which their assigned applications are defined. This key is required to
be false if environment is an empty string |
debug
|
Boolean, whether to use the --debug flag on
Puppet agent runs. |
trace
|
Boolean, whether to use the --trace flag on
Puppet agent runs. |
evaltrace
|
Boolean, whether to use the --evaltrace flag on
Puppet agent runs. |
filetimeout |
Integer, sets the --filetimeout flag on Puppet
agent runs to the provided value. |
http_connect_timeout |
Integer, sets the --http_connect_timeout flag
on Puppet agent runs to the provided value. |
http_keepalive_timeout |
Integer, sets the --http_keepalive_timeout flag
on Puppet agent runs to the provided value. |
http_read_timeout |
Integer, sets the --http_read_timeout flag on
Puppet agent runs to the provided value. |
ordering |
String, sets the --ordering flag on Puppet
agent runs to the provided value. |
skip_tags |
String, sets the --skip_tags flag on Puppet
agent runs to the provided value. |
tags |
String, sets the --tags flag on Puppet agent
runs to the provided value. |
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
|
An object of arbitrary key/value data supplied to the job. |
For example, to deploy the node1.example.com
environment in
no-op mode, the following request is valid:
{
"environment" : "",
"enforce_environment": false,
"noop" : true,
"scope" : {
"nodes" : ["node1.example.com"]
},
"userdata": {
"servicenow_ticket": "INC0011211"
}
}
Copied!
Scope
Scope is a JSON object containing exactly one of these keys:
Key | Definition |
---|---|
application
|
The name of an application or application instance to deploy. If an application type is specified, all instances of that application are deployed. |
nodes
|
A list 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
|
A classifier node group ID. The ID must correspond to a node group that has defined rules. It is not sufficient for parent groups of the node group in question to define rules. The user must also have permissions to view the node group. |
To deploy an application instance in the production
environment:
{
"environment" : "production",
"scope" : {
"application" : "Wordpress_app[demo]"
}
}
Copied!
To deploy a list of nodes:
{
"environment" : "production",
"scope" : {
"nodes" : ["node1.example.com", "node2.example.com"]
}
}
Copied!
To deploy a list of nodes with the certname
value matching a regex:
{
"environment" : "production",
"scope" : {
"query" : ["from", "nodes", ["~", "certname", ".*"]]
}
}
Copied!
To deploy to the nodes defined by the "All Nodes" node group:
{
"environment" : "production",
"scope" : {
"node_group" : "00000000-0000-4000-8000-000000000000"
}
}
Copied!
Response format
If all node runs succeed, and the environment is successfully deployed, the server returns
a 202
response.
The response is a JSON object containing a link to retrieve information about the status of the job and uses any one of these keys:
Key | Definition |
---|---|
id
|
An absolute URL that links to the newly created job. |
name
|
The name of the newly created job. |
For example:
{
"job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234"
"name" : "1234"
}
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/unknown-environment
|
If the environment does not exist, the server returns a
404 response. |
puppetlabs.orchestrator/empty-environment
|
If the environment requested contains no applications or no
nodes, the server returns a 400 response. |
puppetlabs.orchestrator/empty-target
|
If the application instance specified to deploy does not exist
or is empty, the server returns a 400 response. |
puppetlabs.orchestrator/dependency-cycle
|
If the application code contains a cycle, the server returns a
400 response. |
puppetlabs.orchestrator/puppetdb-error
|
If the orchestrator is unable to make a query to PuppetDB, the
server returns a 400 response. |
puppetlabs.orchestrator/query-error
|
If a user does not have appropriate permissions to run a query,
or if the query is invalid, the server returns a 400
response. |
POST /command/schedule_deploy
Schedule a Puppet run on a set of nodes.
Request format
Key | Definition |
---|---|
environment |
The environment to deploy. Required string. |
scope |
A PuppetDB query, a list of nodes, or a classifier node group ID to deploy. Required object. |
scheduled_time |
Timestamp for when to run the scheduled job. If the timestamp
is in the past, a 400 error is
thrown. Required ISO-8601 timestamp. |
Key | Definition |
---|---|
concurrency |
The maximum number of nodes to run at once. The default, if unspecified, is unlimited. Integer. |
debug |
Whether to use the --debug flag on Puppet agent runs. Boolean.
|
description |
Description of the job. String. |
enforce_environment |
Whether to force agents to run in the same environment in
which their assigned applications are defined. This key is
required to be false if
environment is an empty string. Boolean.
|
evaltrace |
Whether to use the --evaltrace flag on Puppet agent runs. Boolean.
|
filetimeout |
Sets the --filetimeout flag on Puppet agent runs to the provided
value. Integer. |
http_connect_timeout |
Sets the --http_connect_timeout flag on Puppet agent runs to the provided
value. Integer. |
http_keepalive_timeout |
Sets the --http_keepalive_timeout flag on
Puppet agent runs to the
provided value. Integer. |
http_read_timeout |
Sets the --http_read_timeout flag on Puppet agent runs to the provided
value. Integer. |
noop |
Whether to run the agent in no-op mode. Defaults to false . Boolean. |
no_noop |
Whether to run the agent in enforcement mode. Defaults to
false . This flag overrides
noop = true if set in the
agent’s configuration and cannot be set to true at the same time
as the noop flag. Boolean.
|
ordering |
Sets the --ordering flag to
the provided value on Puppet
agent runs. String. |
scheduled_time |
The timestamp for when to run the scheduled job. If the
timestamp is in the past, a 400
error is thrown. Required ISO-8601 timestamp. |
schedule_options |
Object. |
interval
|
Object. |
units |
Enum in seconds. |
value |
Positive integer. |
skip_tags |
Sets the --skip_tags flag to
the provided value on Puppet
agent runs. String. |
tags |
Sets the --tags flag to the
provided value on Puppet agent
runs. String. |
trace |
Whether to use the --trace
flag on Puppet agent runs.
Boolean. |
use_cached_catalog |
Whether to use the --use_cached_catalog flag on Puppet agent runs. Boolean.
|
usecacheonfailure |
Whether to use the --usecacheonfailure flag on Puppet agent runs.
Boolean. |
node1.example.com
in noop mode, the
following request is
valid:{
"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!
Response format
If all node runs succeed, and the environment is successfully deployed, the server
returns a 202
response.
Key | Definition |
---|---|
id |
An absolute URL that links to the newly created job. |
name |
The name of the newly created job. |
{
"job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
"name" : "1234"
}
}
Copied!
Error responses
kind
key of the error displays the
conflict. Error | Definition |
---|---|
puppetlabs.orchestrator/unknown-environment |
If the environment does not exist, the server returns a
404 response. |
puppetlabs.orchestrator/empty-environment |
If the environment requested contains no applications or no
nodes, the server returns a 400
response. |
puppetlabs.orchestrator/empty-target |
If the application instance specified to deploy does not
exist or is empty, the server returns a 400
response. |
puppetlabs.orchestrator/dependency-cycle |
If the application code contains a cycle, the server returns
a 400 response. |
puppetlabs.orchestrator/puppetdb-error |
If the orchestrator is unable to make a query to PuppetDB, the server returns a
400 response. |
puppetlabs.orchestrator/query-error |
If a user does not have appropriate permissions to run a
query, or if the query is invalid, the server returns a
400 response. |
POST /command/stop
Stop an orchestrator job that is currently in progress. Puppet agent runs that are in progress finish, but no new agent runs start. While agents are finishing, the server continues to produce events for the job.
The job transitions to status stopped
when all pending agent runs have
finished.
This command is idempotent: it can be issued against the same job any number of times.
Request format
The JSON body of the request must contain the ID of the job to stop. The job ID is the same
value as the name
property returned with the deploy
command.
-
job
: the name of the job to stop.
For example:
{
"job": "1234"
}
Copied!
Response format
If the job is stopped successfully, the server returns a 202
response. The
response uses these keys:
Key | Definition |
---|---|
id
|
An absolute URL that links to the newly created job. |
name
|
The name of the newly created job. |
nodes
|
A hash that shows all of the possible node statuses, and how many nodes are currently in that status. |
For example:
{
"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!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If a job name is not valid, the server returns a
400 response. |
puppetlabs.orchestrator/unknown-job
|
If a job name is unknown, the server returns a
404 response. |
POST /command/task
Run a permitted task job across a set of nodes. Any nodes specified in the scope that you do not have permission to run tasks on are excluded.
Request format
The request body must be a JSON object and uses the following keys:
Key | Definition |
---|---|
environment
|
The environment to load the task from. The default is production . |
scope
|
The PuppetDB query, list of nodes, or a node group ID. Application scopes are not allowed for task jobs. This key is required. |
description
|
A description of the job. |
noop
|
Whether to run the job in no-op mode. The default is false . |
task
|
The task to run on the targets. This key is required. |
params
|
The parameters to pass to the task. This key is required, but can be an empty object. |
targets |
A collection of target objects used for running the task on nodes through SSH or WinRM via Bolt server. |
userdata
|
An object of arbitrary key/value data supplied to the job. |
For example, to run the package
task on node1.example.com
, the following request is valid:
{
"environment" : "test-env-1",
"task" : "package",
"params" : {
"action" : "install",
"name" : "httpd"
},
"scope" : {
"nodes" : ["node1.example.com"]
}
}
Copied!
Scope
Scope is a JSON object containing exactly one of the following keys:
Key | Definition |
---|---|
application |
The name of an application or application instance to deploy. If an application type is specified, all instances of that application will be deployed. This key is only supported for the deploy command. |
nodes
|
An array of node names to target. |
query
|
A PuppetDB or PQL query to use to discover nodes. The target is built from the
certname values collected at the top level of the
query. |
node_group
|
A classifier node group ID. The ID must correspond to a node group that has defined rules. It is not sufficient for parent groups of the node group in question to define rules. The user must also have permissions to view the node group. Any nodes specified in the scope that the user does not have permissions to run the task on are excluded. |
To deploy an application instance in the production environment, the following request is valid:
{
"environment" : "production",
"scope" : {
"application" : "Wordpress_app[demo]"
}
}
Copied!
{
"environment" : "production",
"scope" : {
"nodes" : ["node1.example.com", "node2.example.com"]
}
}
Copied!
certname
value
matching a regex, the following request is
valid:{
"environment" : "production",
"scope" : {
"query" : ["from", "nodes", ["~", "certname", ".*"]]
}
}
Copied!
{
"environment" : "production",
"scope" : {
"node_group" : "00000000-0000-4000-8000-000000000000"
}
}
Copied!
Targets
Key | Definition |
---|---|
hostnames |
Array of hostnames that share the same target attributes. These should each match an entry in the node list scope for the job. String. This key is required. |
password |
Password matching the user specified. One of two credential optional, along
with private-key-content . String. |
private-key-content |
Content of the ssh key used to ssh to the remote node to run on. String. |
port |
Specifies which port on the remote node to use to connect. Integer. |
user |
User on the remote system to log in as to run the task. String. This key is required. |
transport |
Specify ssh or winrm. Stirng. This key is required. |
run-as |
An optional user to run commands when using ssh. String. |
sudo-password |
A password to use when changing users via run-as . String. |
run-as-command |
Command to elevate permissions via run-as .
String. |
connect-timeout |
How long, in seconds, Bolt should wait when establishing connections. Integer. |
tty |
Determines if Bolt uses pseudo tty to meet sudoer restrictions. Boolean. |
tmpdir |
The directory to upload and execute temporary files on the target. String. |
extensions |
List of file extensions that are accepted for scripts or tasks. String. |
For example,
[
{
"hostnames": ["sshnode1.example.com", "sshnode2.example.com"],
"password": "p@ssw0rd",
"port": 4444,
"user": "foo",
"transport": "ssh"
},
{
"hostnames": ["winrmnode.example.com"],
"password": "p@ssw0rd!",
"port": 4444,
"user": "foo",
"transport": "winrm"
}
]
Copied!
Response format
If the task is starts successfully, the response will have a 202
status.
-
id
: an absolute URL that links to the newly created job. -
name
: the name of the newly created job. For example:{ "job" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234", "name" : "1234" } }
Copied!
Error responses
For this endpoint, the kind
key of the error displays the
conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/unknown-environment
|
If the environment does not exist, the server returns a 404 response. |
puppetlabs.orchestrator/empty-target
|
If the application instance specified to deploy does not exist or is empty, the server returns a 400 response. |
puppetlabs.orchestrator/puppetdb-error
|
If the orchestrator is unable to make a query to PuppetDB, the server returns a 400 response. |
puppetlabs.orchestrator/query-error
|
If a user does not have appropriate permissions to run a query, or if the query is invalid, the server returns a 400 response. |
puppetlabs.orchestrator/not-permitted
|
This error occurs when a user does not have permission to run the task on the requested nodes. Server returns a 403 response. |
POST /command/task_target
Create a new task-target, which is a collection of tasks, nodes and node groups that define a permission group. When a user has permissions to run via a given task-target, they are granted permissions to run the given set of tasks, on the set of nodes described by the task-target.
After creating a task-target, use the POST /roles endpoint to create the role that controls the permissions to execute the task-target. For the complete task-target workflow, see the blog post Puppet Enterprise RBAC API, or how to manage access to tasks.
Request format
Key | Definition |
---|---|
display_name |
A required string that is used to name the task-target. No uniqueness requirements |
tasks |
An optional array of tasks that correspond to the
task-target. There is no requirement that the tasks correspond
to existing tasks. If omitted or empty,
all_tasks must be provided and set to
true. |
all_tasks |
An optional boolean to determine if all tasks can be run on
designated targets. Defaults to false. If omitted,
tasks are required to be specified. If both
all_tasks is true and valid tasks are
supplied, tasks are ignored and
all_tasks is set. |
nodes |
An array of certnames that can correspond to both agent and agentless nodes. The user can run the task against the specified nodes. There is no requirement that the nodes correspond to currently available nodes. The array can be empty. |
node_groups |
An array of node-group-ids that describe the set of nodes the task can be run against. The possible nodes described by the node group will be combined with any nodes in the `nodes` array. The array can be empty. |
pql_query |
An optional string that is a single PQL query to fetch nodes that the task-target corresponds to. The query results must contain the certnames key in the results to identify the permitted nodes. |
{
"display_name": "foo",
"tasks": ["abc", "def"],
"nodes": ["node1" "node2"],
"node_groups": ["00000000-0000-4000-8000-000000000000"]
}
{
"display_name": "foo",
"all_tasks": "true",
"nodes": ["node1" "node2"],
"node_groups": ["00000000-0000-4000-8000-000000000000"]
}
Copied!
Response format
If the task-target is successfully created, the server will return a 200 response with a JSON object containing a link to retrieve information about the task-target. The keys of this object are:
-
id
: an absolute URL to retrieve the individual task-target. -
name
: a unique identifier for the task-target.
{
"task_target": {
"id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
"name": "1"
}
}
Copied!
Error responses
kind
key of the error displays the conflict.
See the Orchestrator API error responses documentation for the
general format of error responses.Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error |
If there is no display name supplied, there are no tasks
specified when supplied, task names are not strings,
all_tasks is not a boolean when supplied,
all_tasks is not set to true when tasks are
not supplied, node names are not strings, node-group ids are not
strings, or pql_query is not a string the
service returns a 400 response. |
POST /command/schedule_task
Schedule a task to run at a future date and time.
Request format
The request body must be a JSON object and uses the following keys:
Key | Definition |
---|---|
task
|
The task to run on the targets. Required. |
params
|
The parameters to pass to the task. Required. |
scope
|
The PuppetDB query, list of nodes, or a node group ID. Application scopes are not allowed for task jobs. Required. |
scheduled_time
|
The ISO-8601 timestamp the determines when to run the scheduled job. If timestamp is in the past, a 400 error is thrown. Required. |
schedule_options |
Object. |
interval
|
Object. |
units |
Enum in seconds. |
value |
Positive integer. |
description
|
A description of the job. |
environment
|
The environment to load the task from. The default is production . |
noop
|
Whether to run the job in no-op mode. The default is false. |
For example, to run the package
task on node1.example.com
, the following request is valid:
{
"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!
Response format
If the task schedules successfully the server returns 202.
Key | Definition |
---|---|
id |
An absolute URL that links to the newly created job. |
name |
The name of the newly created job. |
{
"scheduled_job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
"name" : "1234"
}
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the
conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/invalid-time
|
If the |
POST /command/schedule_plan
Schedule a plan to run at a later time. The body consists of the same fields as
/command/plan_run
and a scheduled_time
field.
Request format
Key | Definition |
---|---|
plan |
A required string that indicates which plan to run. |
params |
A required object that indicates which parameters to pass to the plan. |
scheduled_time |
A required ISO 8601 timestamp to indicate when to run the
scheduled job. If the timestamp is in the past, a 400 error will be thrown. |
description |
A description of the job. |
environment |
The environment to load the plan from. The default is production . |
node1.example.com node
,
the following request is valid.{
"environment": "test-env-1",
"plan": "facts",
"params": {
"targets": "node1.example.com"
},
"scheduled_time": "2027-05-05T19:50:08Z"
}
Copied!
Response format
If the plan schedules successfully, the server returns 202.
Key | Definition |
---|---|
id |
An absolute URL that links to the newly created job. |
name |
The name of the newly created job. |
{
"scheduled_job" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
"name" : "1234"
}
}
Copied!
Error responses
kind
key of the error
displays the conflict. Key | Definition |
---|---|
puppetlabs.orchestrator/invalid-time |
If the scheduled_time
provided is in the past, the server returns a
400 response. |
POST /command/plan_run
Run a plan via the plan executor.
Request format
Key | Definition |
---|---|
plan_name |
String, the name of the plan to run. |
params |
Hash, the parameters the job will use. |
environment |
String, environment to load the plan from. The default is
production . |
description |
String, description of the job. |
userdata
|
An object of arbitrary key/value data supplied to the job. |
canary
plan, the following request is valid: {
"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!
Response format
If the plan starts successfully, status 202 is returned.
The response is a JSON object containing the generated plan job name.
{
"name" : "1234"
}
Copied!
Error responses
kind
key of the error displays the conflict.Key | Description |
---|---|
puppetlabs.orchestrator/validation-error |
If the plan name is not valid the server returns a 400
response. |
puppetlabs.orchestrator/not-permitted |
This error occurs if a user makes a request they lack permissions for. The
server returns a 403 response. |
POST /command/environment_plan_run
Run a plan in a specific environment.
Request format
Key | Definition |
---|---|
plan_name |
The name of the plan to run. String. |
params |
The parameters the job will use. Parameters can include queries and node groups by passing the type key as part of the hash for a given parameter. Hash. |
Key | Definition |
---|---|
environment |
The environment to load the plan from. The default is production . String. |
description |
A description of the job. String. |
userdata
|
An object of arbitrary key/value data supplied to the job. |
example_plan
, the following request is valid:
{
"plan_name" : "example_plan",
"description" : "Output 'message' on the targets contained in 'targets' and 'more targets'",
"params": {
"message": {
"value": "hello"
},
"example_hash_param": {
"value": {
"value": "foo"
}
},
"targets": {
"type": "query",
"value": "nodes[certname] { }"
},
"more_targets": {
"type": "node_group",
"value": "<uuid>"
}
}
}
Copied!
In example_plan
, parameters adopt the format
{<param_name>:{"value": <param_value>}}
. Orchestrator
passes <param_value>
as the parameter's value to the plan. The
orchestrator also passes hello
as the message
parameter's value to the plan. For hash parameters, like
example_hash_param
, the hash {"value": "foo"}
is passed to the plan as the value for example_hash_param
. The
type
key is an optional way to give the orchestrator additional
information about the parameter. It is not to be confused with the parameter's type
in the plan metadata.
type
:Value | Definition |
---|---|
query |
The value key is interpreted as a PuppetDB
query. Orchestrator executes the query and passes the resulting
list of nodes as the parameter's value to the plan. For example,
for the targets parameter, if
nodes[certname] { } resolves to the list
["foo_node", "bar_node"] , orchestrator
passes ["foo_node", "bar_node"] into the plan
as the parameter's value. |
node_group |
The value key is interpreted as a node group
UUID. Orchestrator fetches all the nodes that are in this node
group and passes them as the parameter's value to the plan. For
example, for the more_targets parameter, if
<uuid> resolves to
["group_node", "group_node_two"] ,
orchestrator passes that array into the plan as the parameter's
value. |
Response format
If the plan starts successfully, the response has a 202 status. The response is a JSON object containing the generated plan job name.
{
"name" : "1234"
}
Copied!
Error response
See the error response documentation for the general format of error response. For this endpoint, thekind
key
of the error displays the conflict.Key | Description |
---|---|
puppetlabs.orchestrator/validation-error |
If the plan name is not valid the server returns a
400 response. |
puppetlabs.orchestrator/not-permitted |
This error occurs if a user makes a request they lack permissions
for. The server returns a 403 response. |