diff --git a/website/source/api/allocations.html.md b/website/source/api/allocations.html.md index c1b427e63..a02f29845 100644 --- a/website/source/api/allocations.html.md +++ b/website/source/api/allocations.html.md @@ -604,3 +604,48 @@ $ curl -X POST \ "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", "Index": 54 } +``` + +## Signal Allocation + +This endpoint sends a signal to an allocation or task. + +| Method | Path | Produces | +| ------ | -------------------------- | -------------------------- | +| `POST` / `PUT` | `/v1/allocation/:alloc_id/signal` | `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 Payload + +```json +{ + "Signal": "SIGUSR1", + "Task": "FOO" +} +``` + +### Sample Request + +```text +$ curl -X POST -d '{"Signal": "SIGUSR1" }' \ + https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal +``` + +### Sample Response + +```json +{} +``` diff --git a/website/source/docs/commands/alloc.html.md.erb b/website/source/docs/commands/alloc.html.md.erb index a8e3cf574..180f58675 100644 --- a/website/source/docs/commands/alloc.html.md.erb +++ b/website/source/docs/commands/alloc.html.md.erb @@ -20,11 +20,13 @@ subcommands are available: * [`alloc fs`][fs] - Inspect the contents of an allocation directory * [`alloc logs`][logs] - Streams the logs of a task * [`alloc restart`][restart] - Restart a running allocation or task +* [`alloc signal`][signal] - Signal a running allocation * [`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/signal.html "Signal a running allocation" [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/signal.html.md.erb b/website/source/docs/commands/alloc/signal.html.md.erb new file mode 100644 index 000000000..fcc2bd141 --- /dev/null +++ b/website/source/docs/commands/alloc/signal.html.md.erb @@ -0,0 +1,44 @@ +--- +layout: "docs" +page_title: "Commands: alloc signal" +sidebar_current: "docs-commands-alloc-signal" +description: > + Signal a running allocation or task +--- + +# Command: alloc signal + +The `alloc signal` command allows a user to perform an in place signal of an +an entire allocation or individual task. + +## Usage + +``` +nomad alloc signal [options] +``` + +This command accepts a single allocation ID and a task name. The task name must +be part of the allocation and the task must be currently running. The task name +is optional and if omitted every task in the allocation will be signaled. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Signal Options + +* `-s`: Signal to send to the tasks. Valid options depend on the driver. + +* `-verbose`: Display verbose output. + +## Examples + +``` +$ nomad alloc signal eb17e557 + +$ nomad alloc signal eb17e557 foo +Could not find task named: foo, found: +* test + +``` + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index d23465efd..e5811cbaf 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -144,6 +144,9 @@ > restart + > + signal + > status