diff --git a/website/source/api/nodes.html.md b/website/source/api/nodes.html.md new file mode 100644 index 000000000..804166845 --- /dev/null +++ b/website/source/api/nodes.html.md @@ -0,0 +1,271 @@ +--- +layout: api +page_title: Nodes - HTTP API +sidebar_current: api-nodes +description: |- + The /node endpoints are used to query for and interact with client nodes. +--- + +# Nodes HTTP API + +The `/node` endpoints are used to query for and interact with client nodes. + +### List Nodes + +This endpoint lists all nodes registered with Nomad. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/nodes` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `YES` | `all` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter nodes on based on an + index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/nodes +``` + +```text +$ curl \ + https://nomad.rocks/v1/nodes?prefix=prod +``` + +### Sample Response + +```json +[ + { + "ID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "Datacenter": "dc1", + "Name": "bacon-mac", + "NodeClass": "", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "CreateIndex": 5, + "ModifyIndex": 45 + } +] +``` + +## Read Node + +This endpoint queries the status of a client node. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/node/:node_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `YES` | `all` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the ID of the node. This must be + the full UUID, not the short 8-character one. This is specified as part of the + path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c +``` + +### Sample Response + +```json +{ + "ID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "SecretID": "", + "Datacenter": "dc1", + "Name": "bacon-mac", + "HTTPAddr": "127.0.0.1:4646", + "TLSEnabled": false, + "Attributes": { + "os.version": "10.12.5", + "cpu.modelname": "Intel(R) Core(TM) i7-3615QM CPU @ 2.30GHz", + "nomad.revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9", + "driver.docker.volumes.enabled": "1", + "driver.docker": "1", + "cpu.frequency": "2300", + "memory.totalbytes": "17179869184", + "driver.mock_driver": "1", + "kernel.version": "16.6.0", + "unique.network.ip-address": "127.0.0.1", + "nomad.version": "0.5.5dev", + "unique.hostname": "bacon-mac", + "cpu.arch": "amd64", + "os.name": "darwin", + "kernel.name": "darwin", + "unique.storage.volume": "/dev/disk1", + "driver.docker.version": "17.03.1-ce", + "cpu.totalcompute": "18400", + "unique.storage.bytestotal": "249783500800", + "cpu.numcores": "8", + "os.signals": "SIGCONT,SIGSTOP,SIGSYS,SIGINT,SIGIOT,SIGXCPU,SIGSEGV,SIGUSR1,SIGTTIN,SIGURG,SIGUSR2,SIGABRT,SIGALRM,SIGCHLD,SIGFPE,SIGTSTP,SIGIO,SIGKILL,SIGQUIT,SIGXFSZ,SIGBUS,SIGHUP,SIGPIPE,SIGPROF,SIGTRAP,SIGTTOU,SIGILL,SIGTERM", + "driver.raw_exec": "1", + "unique.storage.bytesfree": "142954643456" + }, + "Resources": { + "CPU": 18400, + "MemoryMB": 16384, + "DiskMB": 136332, + "IOPS": 0, + "Networks": [ + { + "Device": "lo0", + "CIDR": "127.0.0.1/32", + "IP": "127.0.0.1", + "MBits": 1000, + "ReservedPorts": null, + "DynamicPorts": null + } + ] + }, + "Reserved": { + "CPU": 0, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": null + }, + "Links": null, + "Meta": null, + "NodeClass": "", + "ComputedClass": "v1:10952212473894849978", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "StatusUpdatedAt": 1495748907, + "CreateIndex": 5, + "ModifyIndex": 45 +} +``` + +## Create Node Evaluation + +This endpoint creates a new evaluation for the given node. This can be used to +force a run of the scheduling logic. + +| Method | Path | Produces | +| ------- | ---------------------------- | -------------------------- | +| `POST` | `/v1/node/:node_id/evaluate` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `NO` | `all` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the UUID of the node. This must + be the full UUID, not the short 8-character one. This is specified as part of + the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/evaluate +``` + +### Sample Response + +```json +{ + "HeartbeatTTL": 0, + "EvalIDs": [ + "4ff1c7a2-c650-4058-f509-d5028ff9566e" + ], + "EvalCreateIndex": 85, + "NodeModifyIndex": 0, + "LeaderRPCAddr": "127.0.0.1:4647", + "NumNodes": 1, + "Servers": [ + { + "RPCAdvertiseAddr": "127.0.0.1:4647", + "RPCMajorVersion": 1, + "RPCMinorVersion": 1, + "Datacenter": "dc1" + } + ], + "Index": 85, + "LastContact": 0, + "KnownLeader": false +} +``` + +## Drain Node + +This endpoint toggles the drain mode of the node. When draining is enabled, no +further allocations will be assigned to this node, and existing allocations will +be migrated to new nodes. + +| Method | Path | Produces | +| ------- | ------------------------- | -------------------------- | +| `POST` | `/v1/node/:node_id/drain` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `NO` | `all` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the UUID of the node. This must + be the full UUID, not the short 8-character one. This is specified as part of + the path. + +- `enable` `(bool: )` - Specifies if drain mode should be enabled. + This is specified as a query string parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/drain?enable=true +``` + +### Sample Response + +```json +{ + "EvalIDs": [ + "253ec083-22a7-76c9-b8b6-2bf3d4b27bfb" + ], + "EvalCreateIndex": 91, + "NodeModifyIndex": 90, + "Index": 90, + "LastContact": 0, + "KnownLeader": false +} +``` diff --git a/website/source/docs/http/node.html.md b/website/source/docs/http/node.html.md deleted file mode 100644 index f716df54d..000000000 --- a/website/source/docs/http/node.html.md +++ /dev/null @@ -1,392 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/node" -sidebar_current: "docs-http-node-" -description: |- - The '/1/node-' endpoint is used to query a specific client node. ---- - -# /v1/node - -The `node` endpoint is used to query the a specific client node. -By default, the agent's local region is used; another region can -be specified using the `?region=` query parameter. - -## GET - -
-
Description
-
- Query the status of a client node registered with Nomad. -
- -
Method
-
GET
- -
URL
-
`/v1/node/`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - { - "ID": "c9972143-861d-46e6-df73-1d8287bc3e66", - "Datacenter": "dc1", - "Name": "Armons-MacBook-Air.local", - "Attributes": { - "arch": "amd64", - "cpu.frequency": "1300.000000", - "cpu.modelname": "Intel(R) Core(TM) i5-4250U CPU @ 1.30GHz", - "cpu.numcores": "2", - "cpu.totalcompute": "2600.000000", - "driver.exec": "1", - "driver.java": "1", - "driver.java.runtime": "Java(TM) SE Runtime Environment (build 1.8.0_05-b13)", - "driver.java.version": "1.8.0_05", - "driver.java.vm": "Java HotSpot(TM) 64-Bit Server VM (build 25.5-b02, mixed mode)", - "hostname": "Armons-MacBook-Air.local", - "kernel.name": "darwin", - "kernel.version": "14.4.0", - "memory.totalbytes": "8589934592", - "network.ip-address": "127.0.0.1", - "os.name": "darwin", - "os.version": "14.4.0", - "storage.bytesfree": "35888713728", - "storage.bytestotal": "249821659136", - "storage.volume": "/dev/disk1" - }, - "Resources": { - "CPU": 2600, - "MemoryMB": 8192, - "DiskMB": 34226, - "IOPS": 0, - "Networks": null - }, - "Reserved": { - "CPU": 0, - "MemoryMB": 0, - "DiskMB": 0, - "IOPS": 0, - "Networks": null - }, - "Links": {}, - "Meta": {}, - "NodeClass": "", - "Drain": false, - "Status": "ready", - "StatusDescription": "", - "CreateIndex": 3, - "ModifyIndex": 4 - } - ``` - -
-
- -
-
Description
-
- Query the allocations belonging to a single node. -
- -
Method
-
GET
- -
URL
-
`/v1/node//allocations`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "ID": "203266e5-e0d6-9486-5e05-397ed2b184af", - "EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455", - "Name": "example.cache[0]", - "NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb", - "JobID": "example", - "ModifyIndex": 9, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 10, - "IP": "", - "CIDR": "", - "Device": "" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "TaskGroup": "cache", - "Job": { - "ModifyIndex": 5, - "CreateIndex": 5, - "StatusDescription": "", - "Status": "", - "Meta": null, - "Update": { - "MaxParallel": 1, - "Stagger": 1e+10 - }, - "TaskGroups": [ - { - "Meta": null, - "Tasks": [ - { - "Meta": null, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "Constraints": null, - "Services": [ - { - "Checks": [ - { - "Timeout": 2e+09, - "Interval": 1e+10, - "Protocol": "", - "Http": "", - "Script": "", - "Type": "tcp", - "Name": "alive", - "Id": "" - } - ], - "PortLabel": "db", - "Tags": [ - "global", - "cache" - ], - "Name": "example-cache-redis", - "Id": "" - } - ], - "Env": null, - "Config": { - "port_map": [ - { - "db": 6379 - } - ], - "image": "redis:latest" - }, - "Driver": "docker", - "Name": "redis" - } - ], - "RestartPolicy": { - "Delay": 2.5e+10, - "Interval": 3e+11, - "Attempts": 10 - }, - "Constraints": null, - "Count": 1, - "Name": "cache" - } - ], - "Region": "global", - "ID": "example", - "Name": "example", - "Type": "service", - "Priority": 50, - "AllAtOnce": false, - "Datacenters": [ - "dc1" - ], - "Constraints": [ - { - "Operand": "=", - "RTarget": "linux", - "LTarget": "${attr.kernel.name}" - } - ] - }, - "TaskResources": { - "redis": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - } - }, - "Metrics": { - "CoalescedFailures": 0, - "AllocationTime": 1590406, - "NodesEvaluated": 1, - "NodesFiltered": 0, - "ClassFiltered": null, - "ConstraintFiltered": null, - "NodesExhausted": 0, - "ClassExhausted": null, - "DimensionExhausted": null, - "Scores": { - "e02b6169-83bd-9df6-69bd-832765f333eb.binpack": 6.133651487695705 - } - }, - "DesiredStatus": "run", - "DesiredDescription": "", - "ClientStatus": "running", - "ClientDescription": "", - "TaskStates": { - "redis": { - "Events": [ - { - "KillError": "", - "Message": "", - "Signal": 0, - "ExitCode": 0, - "DriverError": "", - "Time": 1447806038427841000, - "Type": "Started" - } - ], - "State": "running" - } - }, - "CreateIndex": 7 - }, - ... - ] - ``` - -
-
- -## PUT / POST - -
-
Description
-
- Creates a new evaluation for the given node. This can be used to force - run the scheduling logic if necessary. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/node//evaluate`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "EvalIDs": ["d092fdc0-e1fd-2536-67d8-43af8ca798ac"], - "EvalCreateIndex": 35, - "NodeModifyIndex": 34 - } - ``` - -
-
- -
-
Description
-
- Toggle the drain mode of the node. When enabled, no further - allocations will be assigned and existing allocations will be - migrated. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/node//drain`
- -
Parameters
-
-
    -
  • - enable - required - Boolean value provided as a query parameter to either set - enabled to true or false. -
    • -
-
- -
Returns
-
- - ```javascript - { - "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", - "EvalCreateIndex": 35, - "NodeModifyIndex": 34 - } - ``` - -
-
diff --git a/website/source/docs/http/nodes.html.md b/website/source/docs/http/nodes.html.md deleted file mode 100644 index 8c58ed870..000000000 --- a/website/source/docs/http/nodes.html.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/nodes" -sidebar_current: "docs-http-nodes" -description: |- - The '/1/nodes' endpoint is used to list the client nodes. ---- - -# /v1/nodes - -The `nodes` endpoint is used to query the status of client nodes. -By default, the agent's local region is used; another region can -be specified using the `?region=` query parameter. - -## GET - -
-
Description
-
- Lists all the client nodes registered with Nomad. -
- -
Method
-
GET
- -
URL
-
`/v1/nodes`
- -
Parameters
-
-
    -
  • - prefix - optional - Filter nodes based on an identifier prefix. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "ID": "c9972143-861d-46e6-df73-1d8287bc3e66", - "Datacenter": "dc1", - "Name": "web-8e40e308", - "NodeClass": "", - "Drain": false, - "Status": "ready", - "StatusDescription": "", - "CreateIndex": 3, - "ModifyIndex": 4 - }, - ... - ] - ``` - -
-