Puppet Enterprise 2019.0

Use the command endpoints 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 once. 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.
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 will be deployed. If this key is left blank or unspecified without a scope, the entire environment will be 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 will be 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 will be 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/stop

Stop an orchestrator job that is currently in progress. Puppet agent runs that are in progress will finish, but no new agent runs will start. While agents are finishing, the server will continue to produce events for the job.

The job will transition to status stopped once 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

See the error response documentation for the general format of 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.

Request format

The request body must be a JSON object and uses the following keys:

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

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:

KeyDefinition
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 will be 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"
  }
}

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/plan_start

Mark the beginning of a plan job and generate plan job name.

Request format

The request body must be a JSON object and uses the following keys:

KeyDefinition
plan_name The name of the plan to run.
params The parameters to pass to the job.
description String A 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 200.

The response will be a JSON object containing the generated plan job name. For example:
{
  "name" : "1234"
}

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition

puppetlabs.orchestrator/validation-error

If the plan name is not valid the server returns a 400 response.

puppetlabs.orchestrator/not-permitted

This error occurs when a user does not have a permissions for a request. The server returns a 403 response.

POST /command/plan_finish

Declare the end of a plan run.

Request format

The request body must be a JSON object and uses the following keys:

KeyDefinition
plan_job The ID of the plan job.
result The JSON result object for the plan job.
status Value of success or failure.

To finish the canary plan the following request is valid:

{
  "plan_job": "1",
  "result" : {
    "foo" : "bar",
  },
  "status": "success"
}

Response format

If the plan finishes successfully the response will have status 200.

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition

puppetlabs.orchestrator/unknown-plan-job-name

If the plan name is not valid the server returns a 400 response.

puppetlabs.orchestrator/plan-job-not-owned-by-userWhen the specified plan job was created by another user. The server returns a 403 response.
puppetlabs.orchestrator/tasks-not-completedIf the tasks included in the plan have not yet finished the server will return a 400 response.
puppetlabs.orchestrator/plan-already-endedIf the plan job has already finished the server will return a 400 response.
puppetlabs.orchestrator/not-permittedThis error occurs if a user makes a request they lack permissions for. The server returns a 403 response.

POST /command/plan_task

Run a task from a plan job on a target.

Request format

The request body must be a JSON object and uses the following keys:

KeyDefinition
plan_job The ID for the plan job
task The task to run on the targets.
params The parameters to pass to the task.
scope The PuppetDB query, list of nodes, or a node group ID. Application scopes are not allowed for task jobs.
description 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.

To run the package task on node1.example.com, the following request is valid:

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

Response format

If the plan starts successfully the response will have status 200.

Key Definition
id An absolute URL that links to the newly created job.
name The name of the newly created job.
The response will be a JSON object containing a link to retrieve information about the status of the job. 
{
  "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/invalid-plan-name

If the plan name is not valid the server returns a 400 response.

puppetlabs.orchestrator/plan-job-not-owned-by-user When the specified plan job was created by another user, the server returns a 403 response.
puppetlabs.orchestrator/plan-already-finished When the plan the task is a part of has already finished, the server will return a 400 response.
puppetlabs.orchestrator/not-permitted When a user makes a request they lack permissions for, and the server returns a 403 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:

KeyDefinition
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 will be thrown. Required.
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"
}

Response format

If the task schedules successfully the server returns 202.

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:
{
  "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.

Back to top