2017-05-26 23:15:07 +00:00
|
|
|
---
|
|
|
|
layout: api
|
|
|
|
page_title: Client - HTTP API
|
|
|
|
description: |-
|
2023-02-10 00:03:43 +00:00
|
|
|
The /client endpoints are used to access client information and inspect
|
2018-02-07 20:51:06 +00:00
|
|
|
allocations running on a particular client.
|
2017-05-26 23:15:07 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Client HTTP API
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
The `/v1/client` endpoints are used to interact with the Nomad clients.
|
2018-02-07 20:51:06 +00:00
|
|
|
|
2018-02-14 21:18:08 +00:00
|
|
|
Since Nomad 0.8.0, both a client and server can handle client endpoints. This is
|
|
|
|
particularly useful for when a direct connection to a client is not possible due
|
|
|
|
to the network configuration. 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.
|
2018-02-07 20:51:06 +00:00
|
|
|
|
|
|
|
When accessing the endpoints via the server, if the desired node is ambiguous
|
2018-02-14 21:18:08 +00:00
|
|
|
based on the URL, an additional `?node_id` query parameter must be provided to
|
|
|
|
disambiguate.
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
## Read Node Metadata
|
|
|
|
|
|
|
|
This endpoint queries Node metadata on a specific Client agent and responds
|
|
|
|
with the following fields:
|
|
|
|
|
|
|
|
- `Meta` `(object)` - The Node metadata that will be registered with the Nomad
|
|
|
|
servers and used by the scheduler (after up to 10 seconds of delay for
|
|
|
|
batching). This is the merged version of the `Static` and `Dynamic` fields.
|
|
|
|
|
|
|
|
- `Static` `(object)` - The Node metadata set in the Client agent's
|
|
|
|
configuration file. Only loaded when an agent starts.
|
|
|
|
|
|
|
|
- `Dynamic` `(object)` - The Node metadata set via the API (see below). Unlike
|
|
|
|
`Meta` and `Static`, this object may contain `null` values to differentiate
|
|
|
|
"unset" keys from keys with an empty string value (`""`).
|
|
|
|
|
|
|
|
Note that [`/v1/node/:node_id`][api-node-read] only contains the `Meta` object.
|
|
|
|
It may take up to 10 seconds for dynamic Node metadata to be sent to Servers
|
|
|
|
and visible through the Node API. Use the Node API to see the version of Node
|
|
|
|
metadata the scheduler uses.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------- | ------------------ |
|
|
|
|
| `GET` | `/v1/client/metadata` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------- |
|
|
|
|
| `NO` | `node:read` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:node_id` `(string: <optional>)` - Specifies the node to query.
|
|
|
|
This is required when the endpoint is being accessed via a server. Defaults
|
|
|
|
to the node recieving the request otherwise. This is specified as part of
|
|
|
|
the URL. Note, this must be the _full_ node ID, not the short 8-character
|
|
|
|
one. This must be specified as part of the path (`?node_id=...`).
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ nomad operator api /v1/client/metadata
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
Formatted by appending `?pretty` above.
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Meta": {
|
|
|
|
"connect.proxy_concurrency": "1",
|
|
|
|
"connect.sidecar_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.gateway_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.log_level": "debug",
|
|
|
|
"foo": "bar"
|
|
|
|
},
|
|
|
|
"Dynamic": {
|
|
|
|
"key_to_unset": null,
|
|
|
|
"foo": "bar",
|
|
|
|
"connect.log_level": "debug"
|
|
|
|
},
|
|
|
|
"Static": {
|
|
|
|
"connect.sidecar_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.gateway_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.log_level": "info",
|
|
|
|
"connect.proxy_concurrency": "1"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
## Update Node Metadata
|
|
|
|
|
|
|
|
This endpoint updates dynamic Node metadata on a specific Client agent. Since
|
|
|
|
dynamic Node metadata is only periodically synchronized to Nomad Servers, the
|
|
|
|
`Meta` returned in this API may not be reflected in the
|
|
|
|
[`/v1/node/:node_id`][api-node-read] API for up to 10 seconds. Scheduling uses
|
|
|
|
the Node API version of `Meta`.
|
|
|
|
|
|
|
|
For convenience this endpoint returns the same response as a GET.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------- | ------------------ |
|
|
|
|
| `POST` | `/v1/client/metadata` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------- |
|
|
|
|
| `NO` | `node:write` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `NodeID` or `:node_id` `(string: <optional>)` - Specifies the node to query.
|
|
|
|
This is required when the endpoint is being accessed via a server. Defaults
|
|
|
|
to the node recieving the request otherwise. This is specified as part of
|
|
|
|
the URL. Note, this must be the _full_ node ID, not the short 8-character
|
|
|
|
one. This may be specified as part of the path (`?node_id=...`) or request
|
|
|
|
(`NodeID: "..."`).
|
|
|
|
|
|
|
|
- `Meta` `(object: <required>)` - Specifies the Node metadata keys to update.
|
|
|
|
Only specified keys are updated.
|
|
|
|
|
|
|
|
- `<key>` `(string: <optional>)` - Specifies a metadata key to update to a
|
|
|
|
particular value. Since `""` is a valid value and distinct from unset,
|
|
|
|
the `null` value is used to mark a key as unset. Keys must be valid
|
|
|
|
dotted HCL identifiers. For example `connect.log_level` is a valid key
|
|
|
|
while `some/path` is not.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Meta": {
|
|
|
|
"connect.log_level": "debug",
|
|
|
|
"key_to_unset": null,
|
|
|
|
"foo": "bar"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
Assuming the above payload is in a file called `meta.json`.
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ nomad operator api /v1/client/metadata < meta.json
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
Formatted by appending `?pretty` above.
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Meta": {
|
|
|
|
"connect.proxy_concurrency": "1",
|
|
|
|
"connect.sidecar_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.gateway_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.log_level": "debug",
|
|
|
|
"foo": "bar"
|
|
|
|
},
|
|
|
|
"Dynamic": {
|
|
|
|
"key_to_unset": null,
|
|
|
|
"foo": "bar",
|
|
|
|
"connect.log_level": "debug"
|
|
|
|
},
|
|
|
|
"Static": {
|
|
|
|
"connect.sidecar_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.gateway_image": "envoyproxy/envoy:v${NOMAD_envoy_version}",
|
|
|
|
"connect.log_level": "info",
|
|
|
|
"connect.proxy_concurrency": "1"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-05-26 23:15:07 +00:00
|
|
|
## Read Stats
|
|
|
|
|
|
|
|
This endpoint queries the actual resources consumed on a node. 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.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------------ | ------------------ |
|
|
|
|
| `GET` | `/v1/client/stats` | `application/json` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-05-31 00:31:16 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
2017-10-05 22:43:20 +00:00
|
|
|
| `NO` | `node:read` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2018-02-07 20:51:06 +00:00
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `node_id` `(string: <optional>)` - Specifies the node to query. This is
|
2018-02-14 21:18:08 +00:00
|
|
|
required when the endpoint is being accessed via a server. This is specified as
|
2018-02-07 20:51:06 +00:00
|
|
|
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.
|
|
|
|
|
2017-05-26 23:15:07 +00:00
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api /v1/client/stats
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"AllocDirStats": {
|
|
|
|
"Available": 142943150080,
|
|
|
|
"Device": "",
|
|
|
|
"InodesUsedPercent": 0.05312946180421879,
|
|
|
|
"Mountpoint": "",
|
|
|
|
"Size": 249783500800,
|
|
|
|
"Used": 106578206720,
|
|
|
|
"UsedPercent": 42.668233241448746
|
|
|
|
},
|
|
|
|
"CPU": [
|
|
|
|
{
|
|
|
|
"CPU": "cpu0",
|
|
|
|
"Idle": 80,
|
|
|
|
"System": 11,
|
|
|
|
"Total": 20,
|
|
|
|
"User": 9
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu1",
|
|
|
|
"Idle": 99,
|
|
|
|
"System": 0,
|
|
|
|
"Total": 1,
|
|
|
|
"User": 1
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu2",
|
|
|
|
"Idle": 89,
|
|
|
|
"System": 7.000000000000001,
|
|
|
|
"Total": 11,
|
|
|
|
"User": 4
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu3",
|
|
|
|
"Idle": 100,
|
|
|
|
"System": 0,
|
|
|
|
"Total": 0,
|
|
|
|
"User": 0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu4",
|
|
|
|
"Idle": 92.92929292929293,
|
|
|
|
"System": 4.040404040404041,
|
|
|
|
"Total": 7.07070707070707,
|
|
|
|
"User": 3.0303030303030303
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu5",
|
|
|
|
"Idle": 99,
|
|
|
|
"System": 1,
|
|
|
|
"Total": 1,
|
|
|
|
"User": 0
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu6",
|
|
|
|
"Idle": 92.07920792079209,
|
|
|
|
"System": 4.9504950495049505,
|
|
|
|
"Total": 7.920792079207921,
|
|
|
|
"User": 2.9702970297029703
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"CPU": "cpu7",
|
|
|
|
"Idle": 99,
|
|
|
|
"System": 0,
|
|
|
|
"Total": 1,
|
|
|
|
"User": 1
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"CPUTicksConsumed": 1126.8044804480448,
|
2020-12-18 17:30:26 +00:00
|
|
|
"DeviceStats": [
|
|
|
|
{
|
|
|
|
"InstanceStats": {
|
|
|
|
"6a61929e-d572-092d-5921-156a913f8e56": {
|
|
|
|
"Stats": {
|
|
|
|
"Attributes": {
|
|
|
|
"Used Memory": {
|
|
|
|
"Desc": "Memory in use by the device",
|
|
|
|
"IntNumeratorVal": 128,
|
|
|
|
"Unit": "MiB"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Nested": {}
|
|
|
|
},
|
|
|
|
"Summary": {
|
|
|
|
"Desc": "Memory in use by the device",
|
|
|
|
"IntNumeratorVal": 128,
|
|
|
|
"Unit": "MiB"
|
|
|
|
},
|
|
|
|
"Timestamp": "2020-12-18T17:15:08.949806Z"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Name": "modelA",
|
|
|
|
"Type": "skeleton",
|
|
|
|
"Vendor": "hashicorp"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"InstanceStats": {
|
|
|
|
"73af5d3e-00f9-0786-9bc1-8f5ffa953f15": {
|
|
|
|
"Stats": {
|
|
|
|
"Attributes": {
|
|
|
|
"Used Memory": {
|
|
|
|
"Desc": "Memory in use by the device",
|
|
|
|
"IntNumeratorVal": 128,
|
|
|
|
"Unit": "MiB"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Nested": {}
|
|
|
|
},
|
|
|
|
"Summary": {
|
|
|
|
"Desc": "Memory in use by the device",
|
|
|
|
"IntNumeratorVal": 128,
|
|
|
|
"Unit": "MiB"
|
|
|
|
},
|
|
|
|
"Timestamp": "2020-12-18T17:15:08.949806Z"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Name": "modelB",
|
|
|
|
"Type": "skeleton",
|
|
|
|
"Vendor": "hashicorp"
|
|
|
|
}
|
|
|
|
],
|
2017-05-26 23:15:07 +00:00
|
|
|
"DiskStats": [
|
|
|
|
{
|
|
|
|
"Available": 142943150080,
|
|
|
|
"Device": "/dev/disk1",
|
|
|
|
"InodesUsedPercent": 0.05312946180421879,
|
|
|
|
"Mountpoint": "/",
|
|
|
|
"Size": 249783500800,
|
|
|
|
"Used": 106578206720,
|
|
|
|
"UsedPercent": 42.668233241448746
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"Memory": {
|
|
|
|
"Available": 6232244224,
|
|
|
|
"Free": 470618112,
|
|
|
|
"Total": 17179869184,
|
|
|
|
"Used": 10947624960
|
|
|
|
},
|
|
|
|
"Timestamp": 1495743032992498200,
|
|
|
|
"Uptime": 193520
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-02-07 20:51:06 +00:00
|
|
|
## Read Allocation Statistics
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The client `allocation` endpoint is used to query the actual resources consumed
|
2018-02-07 20:51:06 +00:00
|
|
|
by an allocation.
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------------------- | ------------------ |
|
|
|
|
| `GET` | `/v1/client/allocation/:alloc_id/stats` | `application/json` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-06 00:33:05 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | -------------------- |
|
|
|
|
| `NO` | `namespace:read-job` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/stats
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"ResourceUsage": {
|
|
|
|
"CpuStats": {
|
2020-02-06 23:45:31 +00:00
|
|
|
"Measured": ["Throttled Periods", "Throttled Time", "Percent"],
|
2017-05-26 23:15:07 +00:00
|
|
|
"Percent": 0.14159538847117795,
|
|
|
|
"SystemMode": 0,
|
|
|
|
"ThrottledPeriods": 0,
|
|
|
|
"ThrottledTime": 0,
|
|
|
|
"TotalTicks": 3.256693934837093,
|
|
|
|
"UserMode": 0
|
|
|
|
},
|
|
|
|
"MemoryStats": {
|
|
|
|
"Cache": 1744896,
|
|
|
|
"KernelMaxUsage": 0,
|
|
|
|
"KernelUsage": 0,
|
|
|
|
"MaxUsage": 4710400,
|
2020-02-06 23:45:31 +00:00
|
|
|
"Measured": ["RSS", "Cache", "Swap", "Max Usage"],
|
2017-05-26 23:15:07 +00:00
|
|
|
"RSS": 1486848,
|
|
|
|
"Swap": 0
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Tasks": {
|
|
|
|
"redis": {
|
|
|
|
"Pids": null,
|
|
|
|
"ResourceUsage": {
|
|
|
|
"CpuStats": {
|
2020-02-06 23:45:31 +00:00
|
|
|
"Measured": ["Throttled Periods", "Throttled Time", "Percent"],
|
2017-05-26 23:15:07 +00:00
|
|
|
"Percent": 0.14159538847117795,
|
|
|
|
"SystemMode": 0,
|
|
|
|
"ThrottledPeriods": 0,
|
|
|
|
"ThrottledTime": 0,
|
|
|
|
"TotalTicks": 3.256693934837093,
|
|
|
|
"UserMode": 0
|
|
|
|
},
|
|
|
|
"MemoryStats": {
|
|
|
|
"Cache": 1744896,
|
|
|
|
"KernelMaxUsage": 0,
|
|
|
|
"KernelUsage": 0,
|
|
|
|
"MaxUsage": 4710400,
|
2020-02-06 23:45:31 +00:00
|
|
|
"Measured": ["RSS", "Cache", "Swap", "Max Usage"],
|
2017-05-26 23:15:07 +00:00
|
|
|
"RSS": 1486848,
|
|
|
|
"Swap": 0
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Timestamp": 1495743243970720000
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"Timestamp": 1495743243970720000
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Read File
|
|
|
|
|
|
|
|
This endpoint reads the contents of a file in an allocation directory.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ----------------------------- | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/cat/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------------- |
|
|
|
|
| `NO` | `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `path` `(string: "/")` - Specifies the path of the file to read, relative to
|
|
|
|
the root of the allocation directory.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=alloc/file.json
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```text
|
|
|
|
(whatever was in the file...)
|
|
|
|
```
|
|
|
|
|
|
|
|
## Read File at Offset
|
|
|
|
|
|
|
|
This endpoint reads the contents of a file in an allocation directory at a
|
|
|
|
particular offset and limit.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------------------- | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/readat/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------------- |
|
|
|
|
| `NO` | `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `path` `(string: "/")` - Specifies the path of the file to read, relative to
|
|
|
|
the root of the allocation directory.
|
|
|
|
|
|
|
|
- `offset` `(int: <required>)` - Specifies the byte offset from where content
|
|
|
|
will be read.
|
|
|
|
|
|
|
|
- `limit` `(int: <required>)` - Specifies the number of bytes to read from the
|
|
|
|
offset.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/readat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/foo&offset=1323&limit=19303
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```text
|
|
|
|
(whatever was in the file, starting from offset, up to limit bytes...)
|
|
|
|
```
|
|
|
|
|
|
|
|
## Stream File
|
|
|
|
|
|
|
|
This endpoint streams the contents of a file in an allocation directory.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------------------- | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/stream/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------------- |
|
|
|
|
| `NO` | `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `path` `(string: "/")` - Specifies the path of the file to read, relative to
|
|
|
|
the root of the allocation directory.
|
|
|
|
|
2019-08-01 12:32:43 +00:00
|
|
|
- `follow` `(bool: true)`- Specifies whether to tail the file.
|
|
|
|
|
2017-05-26 23:15:07 +00:00
|
|
|
- `offset` `(int: <required>)` - Specifies the byte offset from where content
|
|
|
|
will be read.
|
|
|
|
|
|
|
|
- `origin` `(string: "start|end")` - Applies the relative offset to either the
|
|
|
|
start or end of the file.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/stream/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/logs/redis.log
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
2020-02-06 23:45:31 +00:00
|
|
|
({
|
2017-05-26 23:15:07 +00:00
|
|
|
"File": "alloc/logs/redis.log",
|
|
|
|
"Offset": 3604480,
|
|
|
|
"Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..."
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"File": "alloc/logs/redis.log",
|
|
|
|
"FileEvent": "file deleted"
|
2020-02-06 23:45:31 +00:00
|
|
|
})
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
#### Field Reference
|
|
|
|
|
|
|
|
The return value is a stream of frames. These frames contain the following
|
|
|
|
fields:
|
|
|
|
|
|
|
|
- `Data` - A base64 encoding of the bytes being streamed.
|
|
|
|
|
|
|
|
- `FileEvent` - An event that could cause a change in the streams position. The
|
|
|
|
possible values are "file deleted" and "file truncated".
|
|
|
|
|
|
|
|
- `Offset` - Offset is the offset into the stream.
|
|
|
|
|
|
|
|
- `File` - The name of the file being streamed.
|
|
|
|
|
|
|
|
## Stream Logs
|
|
|
|
|
2023-04-24 14:00:27 +00:00
|
|
|
This endpoint streams a task's stderr/stdout logs. Note that if logging is set
|
|
|
|
to [enabled=false][] for the task, this endpoint will return a 404 error.
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------------------------ | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/logs/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | -------------------------------------------- |
|
|
|
|
| `NO` | `namespace:read-logs` or `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `task` `(string: <required>)` - Specifies the name of the task inside the
|
|
|
|
allocation to stream logs from.
|
|
|
|
|
|
|
|
- `follow` `(bool: false)`- Specifies whether to tail the logs.
|
|
|
|
|
|
|
|
- `type` `(string: "stderr|stdout")` - Specifies the stream to stream.
|
|
|
|
|
|
|
|
- `offset` `(int: 0)` - Specifies the offset to start streaming from.
|
|
|
|
|
|
|
|
- `origin` `(string: "start|end")` - Specifies either "start" or "end" and
|
|
|
|
applies the offset relative to either the start or end of the logs
|
|
|
|
respectively. Defaults to "start".
|
|
|
|
|
|
|
|
- `plain` `(bool: false)` - Return just the plain text without framing. This can
|
|
|
|
be useful when viewing logs in a browser.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/logs/5fc98185-17ff-26bc-a802-0c74fa471c99
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
2020-02-06 23:45:31 +00:00
|
|
|
({
|
2017-05-26 23:15:07 +00:00
|
|
|
"File": "alloc/logs/redis.stdout.0",
|
|
|
|
"Offset": 3604480,
|
|
|
|
"Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..."
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"File": "alloc/logs/redis.stdout.0",
|
|
|
|
"FileEvent": "file deleted"
|
2020-02-06 23:45:31 +00:00
|
|
|
})
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
#### Field Reference
|
|
|
|
|
|
|
|
The return value is a stream of frames. These frames contain the following
|
|
|
|
fields:
|
|
|
|
|
|
|
|
- `Data` - A base64 encoding of the bytes being streamed.
|
|
|
|
|
|
|
|
- `FileEvent` - An event that could cause a change in the streams position. The
|
|
|
|
possible values are "file deleted" and "file truncated".
|
|
|
|
|
|
|
|
- `Offset` - Offset is the offset into the stream.
|
|
|
|
|
|
|
|
- `File` - The name of the file being streamed.
|
|
|
|
|
|
|
|
## List Files
|
|
|
|
|
|
|
|
This endpoint lists files in an allocation directory.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ---------------------------- | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/ls/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------------- |
|
|
|
|
| `NO` | `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `path` `(string: "/")` - Specifies the path of the file to read, relative to
|
|
|
|
the root of the allocation directory.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/ls/5fc98185-17ff-26bc-a802-0c74fa471c99
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
{
|
|
|
|
"Name": "alloc",
|
|
|
|
"IsDir": true,
|
|
|
|
"Size": 4096,
|
|
|
|
"FileMode": "drwxrwxr-x",
|
|
|
|
"ModTime": "2016-03-15T15:40:00.414236712-07:00"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"Name": "redis",
|
|
|
|
"IsDir": true,
|
|
|
|
"Size": 4096,
|
|
|
|
"FileMode": "drwxrwxr-x",
|
|
|
|
"ModTime": "2016-03-15T15:40:56.810238153-07:00"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Stat File
|
|
|
|
|
|
|
|
This endpoint stats a file in an allocation.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------------------------ | ------------ |
|
|
|
|
| `GET` | `/v1/client/fs/stat/:alloc_id` | `text/plain` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-05-26 23:15:07 +00:00
|
|
|
|
2017-10-05 00:01:32 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------------- |
|
|
|
|
| `NO` | `namespace:read-fs` |
|
2017-05-26 23:15:07 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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.
|
|
|
|
|
|
|
|
- `path` `(string: "/")` - Specifies the path of the file to read, relative to
|
|
|
|
the root of the allocation directory.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/fs/stat/5fc98185-17ff-26bc-a802-0c74fa471c99
|
2017-05-26 23:15:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Name": "redis-syslog-collector.out",
|
|
|
|
"IsDir": false,
|
|
|
|
"Size": 96,
|
|
|
|
"FileMode": "-rw-rw-r--",
|
|
|
|
"ModTime": "2016-03-15T15:40:56.822238153-07:00"
|
|
|
|
}
|
|
|
|
```
|
2017-10-09 18:27:28 +00:00
|
|
|
|
|
|
|
## GC Allocation
|
|
|
|
|
2018-02-07 20:51:06 +00:00
|
|
|
This endpoint forces a garbage collection of a particular, stopped allocation
|
2021-01-04 16:34:12 +00:00
|
|
|
on a node. Note that the allocation will still exist on the server and appear
|
|
|
|
in server responses.
|
2018-02-07 20:51:06 +00:00
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------------------------------ | ------------------ |
|
|
|
|
| `GET` | `/v1/client/allocation/:alloc_id/gc` | `application/json` |
|
2018-02-07 20:51:06 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2018-02-07 20:51:06 +00:00
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ---------------------- |
|
|
|
|
| `NO` | `namespace:submit-job` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:alloc_id` `(string: <required>)` - 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
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api \
|
|
|
|
/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/gc
|
2018-02-07 20:51:06 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## GC All Allocation
|
|
|
|
|
2017-10-09 18:27:28 +00:00
|
|
|
This endpoint forces a garbage collection of all stopped allocations on a node.
|
|
|
|
|
2023-02-10 00:03:43 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------- | ------------ |
|
|
|
|
| `GET` | `/v1/client/gc` | `text/plain` |
|
2017-10-09 18:27:28 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-10-09 18:27:28 +00:00
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `node:write` |
|
|
|
|
|
2018-02-07 20:51:06 +00:00
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `node_id` `(string: <optional>)` - Specifies the node to target. This is
|
2018-02-14 21:18:08 +00:00
|
|
|
required when the endpoint is being accessed via a server. This is specified as
|
2018-02-07 20:51:06 +00:00
|
|
|
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.
|
|
|
|
|
2017-10-09 18:27:28 +00:00
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2023-02-10 00:03:43 +00:00
|
|
|
$ nomad operator api /v1/client/gc
|
2017-10-09 18:27:28 +00:00
|
|
|
```
|
2023-02-10 00:03:43 +00:00
|
|
|
|
|
|
|
[api-node-read]: /nomad/api-docs/nodes
|
2023-04-24 14:00:27 +00:00
|
|
|
[enabled=false]: /nomad/docs/job-specification/logs#enabled
|