Merge pull request #5597 from hashicorp/dani/doc-alloc-stop

Documentation for `nomad alloc stop`

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: <required>)`- 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
+}

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"

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] <allocation>
+```
+
+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
+```
+

website/source/layouts/docs.erb

@@ -147,6 +147,9 @@
               <li<%= sidebar_current("docs-commands-alloc-status") %>>
                 <a href="/docs/commands/alloc/status.html">status</a>
               </li>
+              <li<%= sidebar_current("docs-commands-alloc-stop") %>>
+                <a href="/docs/commands/alloc/stop.html">stop</a>
+              </li>
             </ul>
           </li>
           <li<%= sidebar_current("docs-commands-deployment") %>>