Puppet Enterprise 2018.1

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.
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.