diff --git a/website/source/api/client.html.md b/website/source/api/client.html.md index e2af474b9..edff9a78d 100644 --- a/website/source/api/client.html.md +++ b/website/source/api/client.html.md @@ -3,15 +3,21 @@ layout: api page_title: Client - HTTP API sidebar_current: api-client description: |- - The /client endpoints interact with the local Nomad agent to interact with - client members. + The /client endpoints are used to access client statistics and inspect + allocations running on a particular client. --- # Client HTTP API -The `/client` endpoints are used to interact with the Nomad clients. The API -endpoints are hosted by the Nomad client and requests have to be made to the -Client where the particular allocation was placed. +The `/client` endpoints are used to interact with the Nomad clients. + +Since Nomad 0.8.0, both a client and server can handle client endpoints. For +high volume access to the client endpoints, particularly endpoints streaming +file contents, direct access to the node should be preferred as it avoids adding +additional load to the servers. + +When accessing the endpoints via the server, if the desired node is ambiguous +based on the URL, additional query parameters must be provided to disambiguate. ## Read Stats @@ -31,6 +37,13 @@ The table below shows this endpoint's support for | ---------------- | ------------ | | `NO` | `node:read` | +### Parameters + +- `node_id` `(string: )` - Specifies the node to query. This is + required when the endpoint is being access via a server. This is specified as + part of the URL. Note, this must be the _full_ node ID, not the short + 8-character one. This is specified as part of the path. + ### Sample Request ```text @@ -132,12 +145,10 @@ $ curl \ } ``` -## Read Allocation +## Read Allocation Statistics The client `allocation` endpoint is used to query the actual resources consumed -by an allocation. The API endpoint is hosted by the Nomad client and requests -have to be made to the nomad client whose resource usage metrics are of -interest. +by an allocation. | Method | Path | Produces | | ------ | ------------------------------------ | -------------------------- | @@ -563,9 +574,37 @@ $ curl \ ## GC Allocation +This endpoint forces a garbage collection of a particular, stopped allocation +on a node. + +| Method | Path | Produces | +| ------ | --------------------------------- | -------------------------- | +| `GET` | `/client/allocation/:alloc_id/gc` | `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:submit-job` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/gc +``` + +## GC All Allocation + This endpoint forces a garbage collection of all stopped allocations on a node. -The API endpoint is hosted by the Nomad client and requests have to be made to -the Nomad client whose allocations should be garbage collected. | Method | Path | Produces | | ------ | ---------------------------- | -------------------------- | @@ -579,6 +618,13 @@ The table below shows this endpoint's support for | ---------------- | ------------ | | `NO` | `node:write` | +### Parameters + +- `node_id` `(string: )` - Specifies the node to target. This is + required when the endpoint is being access via a server. This is specified as + part of the URL. Note, this must be the _full_ node ID, not the short + 8-character one. This is specified as part of the path. + ### Sample Request ```text