Puppet orchestrator API: command endpoint

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, a classifier node group id, or an application/application instance 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 Integer, the maximum number of nodes to run at one time. The default, if unspecified, is unlimited.
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.
target String,  required unless scope is specified. The name of an application or application instance to deploy. If an application is specified, all instances of that application are deployed. If this key is left blank or unspecified without a scope, the entire environment is deployed. This key is deprecated.

For example, to deploy the node1.example.com environment in no-op mode, the following request is valid:

{
  "environment" : "",
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  }
}

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

To deploy a list of nodes:

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

To deploy a list of nodes with the certname value matching a regex:

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

To deploy to the nodes defined by the "All Nodes" node group:

{
  "environment" : "production",
  "scope" : {
    "node_group" : "00000000-0000-4000-8000-000000000000"
  }
}

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

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

The request body must be a JSON object. The following keys are required:
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 will be thrown. Required ISO-8601 timestamp.
The following keys are optional:
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 will be 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.
To deploy 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
    }
  }
}

Response format

If all node runs succeed, and the environment is successfully deployed, the server returns a 202 response.

The response will be a JSON object containing a link to retrieve information about the status of the job. The keys of this object are as follows:
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"
  }
}

Error responses

See the error response documentation for the general format of error responses. For this endpoint, the 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"
}

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

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 will be 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.

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

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]"
  }
}
To run a task on a list of nodes, the following request is valid:
{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}
To run a task on a list of nodes with the certname value matching a regex, the following request is valid:
{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}
To deploy to the nodes defined by the "All Nodes" node group the following request is valid:
{
  "environment" : "production",
  "scope" : {
    "node_group" : "00000000-0000-4000-8000-000000000000"
  }
}

Targets

Targets is an array of JSON objects, each containing the following keys:
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"
  }
]

Response format

If the task is starts successfully, the response will have a 202 status.

The response will be a JSON object containing a link to retrieve information about the status of the job. The keys of this object are:
  • 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"
      }
    }

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

Request format

The request body must be a JSON object and uses the following keys:
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.
For example:
{
  "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"]
}

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.
For example:
{
  "task_target": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
    "name": "1"
  }
}

Error responses

For this endpoint, the kind key of the error displays the conflict. See the Puppet 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
    }
  }
}

Response format

If the task schedules successfully the server returns 202.

The response is a JSON object containing a link to retrieve information about the status of the job. The following keys are available.
Key Definition
id An absolute URL that links to the newly created job.
name The name of the newly created job.
For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
    "name" : "1234"
  }
}

Error responses

For this endpoint, the 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

The request body must be a JSON object. The following keys are available:
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.
To start the 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
  }
}

Response format

If the plan starts successfully, the response will have status 202.

The response will be a JSON object containing the generated plan job name.

For example:
{
  "name" : "1234"
}

Error responses

See the error response documentation for the general format of error response. For this endpoint, the 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.
How helpful was this page?

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.