POST /command/stop_plan

Stop an orchestrator plan job that is currently in progress.

This command interrupts the thread that is running the plan.

If the plan doesn't have code to explicitly handle the interrupt, the plan finishes with an error. If the plan can handle the interrupt, whether or not the plan stops depends on the plan's interruption handling.

If the plan is running a task (or otherwise) when interrupted, an error occurs and the plan stops, but the underlying in-progress task job finishes. If you need to force stop an in-progress job, use POST /command/stop.

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 plan_job key, which specifies the string-formatted ID of the plan job to stop, such as:

{
  "plan_job": "1234"
}

The plan_job ID is the name value that is returned from POST /command/plan_run and GET /plan_jobs.

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_plan"
data='{"plan_job": "1234"}'

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

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

Response format

If the specified plan job exists, the server returns a 202 response containing the name key, which is the same as the plan_job key in the request. For example:

{
  "name": "1234"
}

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 plan job ID is not formatted correctly or is otherwise not valid.
404	puppetlabs.orchestrator/unknown-job	The specified plan job ID does not exist.