POST /command/deploy

Run Puppet on demand – run the orchestrator across all nodes in an environment.

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. 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: `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`: The ID of a classifier node group that has defined rules. The node group itself must have defined rules – It is not sufficient for only the node group's parent groups to define rules. The user submitting the request must also have permissions to view the specified node group. Required if `environment` is an empty string. Originally said "required unless 'target' is specified, but 'target' isn't a parameter on this endpoint. I think it meant if environment is an empty string, based on the description of 'enforce_environment'. It may also be always required, based on the key's description in POST /command/schedule_deploy
`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 `global_concurrent_compiles`, refer to Orchestrator and pe-orchestration-services parameters.
`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 specified environment. 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`. how can they both be false? wouldn't one have to be 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.
`timeout`	Integer	The maximum number of seconds a deploy job can take to execute on any individual node. Job execution on a node is forcibly ended if the timeout limit is reached. If unspecified, this key takes the value of `default-deploy-node-timeout`, which is one of the Orchestrator and pe-orchestration-services parameters.
`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.

Here is an example of a complete curl command for the /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"

The following are additional examples of valid JSON bodies for the /command/deploy endpoint.

This body deploys two specific nodes in the production environment:

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

This body deploys the node1.example.com node in no-op mode:

{
  "environment" : "",
  "enforce_environment": false,
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  },
  "userdata": {
    "servicenow_ticket": "INC0011211"
  }
}

This body deploys any node in the production environment with a certname value matching a regex:

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

Response format

If all node runs succeed and the environment is successfully deployed, the server returns 202 and a JSON object using these keys:

id: An absolute URL that links to the newly created job.
name: A stringified number identifying the newly created job. You can use this with other endpoints, such as GET /jobs/<job-id> (retrieve information about the status of the job) and POST /command/stop.

For example:

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
    "name" : "81"
  }
}

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-environment`	The specified `environment` contains no applications or no nodes.
400	`puppetlabs.orchestrator/empty-target`	The specified `scope` resolves to an empty list of nodes.
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.