POST /command/stop

Stop an orchestrator job that is currently in progress.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the job key, which specifies the job ID of the job to stop, such as:

{
  "job": "1234"
}

Job IDs are returned in responses from POST /command/deploy and GET /jobs.

By default, this request halts the specified job. This prevents the job from starting new Puppet agent runs but allows any in-progress runs to finish. While in-progress runs are finishing, the server continues to produce events for the job. The job's status changes to stopped once all in-progress runs finish.

If you want to completely stop the job (to stop in-progress runs and prevent new runs from starting), add the force key to the request, such as:
{
  "job": "1234"
  "force": true
}

You can force, for example, to stop a task that is hanging. Be aware that force immediately ends the job. This can result in an inconsistent or undesirable state due to job components (tasks, plans, Puppet runs, and so on) being ended prematurely.

Here is an example of a complete curl command:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/stop"
data='{"job": "1234"}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

POST /command/stop is idempotent – you can use it against the same job any number of times.

Response format

If the job is stopped successfully, the server returns a 202 response and a JSON object containing these keys:

  • id: An absolute URL that links to the stopped job. This is based on the job key in the request.
  • name: A stringified number identifying the stopped job.
  • nodes: A hash showing all possible node statuses, and how many nodes are currently in each 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
    }
  }
}
When a job is successfully stopped, any in-progress Puppet agent runs finish, but no new agent runs start. While agents are finishing, the server continues to produce events for the job, and the job itself transitions to stopped status when all in-progress agent runs have finished.

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code Key Definition
400 puppetlabs.orchestrator/validation-error The specified job ID is not formatted correctly or is otherwise not valid.
404 puppetlabs.orchestrator/unknown-job The specified job ID does not exist.