diff --git a/website/source/api/allocations.html.md b/website/source/api/allocations.html.md index 06f3f42f2..c1b427e63 100644 --- a/website/source/api/allocations.html.md +++ b/website/source/api/allocations.html.md @@ -567,3 +567,40 @@ $ curl \ - `Building Task Directory` - Task is building its file system. Depending on the type the event will have applicable annotations. + +## Stop Allocation + +This endpoint stops and reschedules a specific allocation. + +| Method | Path | Produces | +| ------ | -------------------------- | -------------------------- | +| `POST` / `PUT` | `/v1/allocation/:alloc_id/stop` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | -------------------- | +| `NO` | `namespace:alloc-lifecycle` | + +### Parameters + +- `:alloc_id` `(string: )`- Specifies the UUID of the allocation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +### Sample Request + +```text +$ curl -X POST \ + https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop +``` + +### Sample Response + +```json +{ + "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Index": 54 +} diff --git a/website/source/docs/commands/alloc.html.md.erb b/website/source/docs/commands/alloc.html.md.erb index 9cb873c54..a8e3cf574 100644 --- a/website/source/docs/commands/alloc.html.md.erb +++ b/website/source/docs/commands/alloc.html.md.erb @@ -21,8 +21,10 @@ subcommands are available: * [`alloc logs`][logs] - Streams the logs of a task * [`alloc restart`][restart] - Restart a running allocation or task * [`alloc status`][status] - Display allocation status information and metadata +* [`alloc stop`][stop] - Stop and reschedule a running allocation [fs]: /docs/commands/alloc/fs.html "Inspect the contents of an allocation directory" [logs]: /docs/commands/alloc/logs.html "Streams the logs of a task" [restart]: /docs/commands/alloc/restart.html "Restart a running allocation or task" [status]: /docs/commands/alloc/status.html "Display allocation status information and metadata" +[stop]: /docs/commands/alloc/stop.html "Stop and reschedule a running allocation" diff --git a/website/source/docs/commands/alloc/stop.html.md.erb b/website/source/docs/commands/alloc/stop.html.md.erb new file mode 100644 index 000000000..eaf018698 --- /dev/null +++ b/website/source/docs/commands/alloc/stop.html.md.erb @@ -0,0 +1,56 @@ +--- +layout: "docs" +page_title: "Commands: alloc stop" +sidebar_current: "docs-commands-alloc-stop" +description: > + Stop and reschedule a running allocation +--- + +# Command: alloc stop + +The `alloc stop` command allows a user to perform an in-place restart of an +entire allocation or individual task. + +## Usage + +``` +nomad alloc stop [options] +``` + +The `alloc stop` command requires a single argument, specifying the alloc ID or +prefix to stop. If there is an exact match based on the provided alloc ID or +prefix, then the alloc will be stopped and rescheduled. Otherwise, a list of +matching allocs and information will be displayed. + +Stop will issue a request to stop and reschedule the allocation. An interactive +monitoring session will display log lines as the allocation completes shutting +down. It is safe to exit the monitor early with ctrl-c. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Stop Options + +* `-detach`: Return immediately instead of entering monitor mode. After the + stop command is submitted, a new evaluation ID is printed to the + screen, which can be used to examine the rescheduling evaluation using the + [eval status](/docs/commands/eval-status.html) command. + +* `-verbose`: Display verbose output. + +## Examples + +``` +$ nomad alloc stop c1488bb5 +==> Monitoring evaluation "26172081" + Evaluation triggered by job "example" + Allocation "4dcb1c98" created: node "b4dc52b9", group "cache" + Evaluation within deployment: "c0c594d0" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "26172081" finished with status "complete" + +$ nomad alloc stop -detach eb17e557 +8a91f0f3-9d6b-ac83-479a-5aa186ab7795 +``` + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index aa3a9ca78..d23465efd 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -147,6 +147,9 @@ > status + > + stop + >