open-nomad/website/source/api/nodes.html.md

904 lines
24 KiB
Markdown
Raw Normal View History

2017-05-26 23:17:07 +00:00
---
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
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
2017-05-26 23:17:07 +00:00
[required ACLs](/api/index.html#acls).
2017-05-31 00:31:16 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
2017-09-15 05:01:18 +00:00
| `YES` | `node:read` |
2017-05-26 23:17:07 +00:00
### 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 \
2018-04-12 18:34:01 +00:00
http://localhost:4646/v1/nodes
2017-05-26 23:17:07 +00:00
```
```text
$ curl \
2018-04-12 18:34:01 +00:00
http://localhost:4646/v1/nodes?prefix=prod
2017-05-26 23:17:07 +00:00
```
### Sample Response
```json
[
{
2018-04-12 18:34:01 +00:00
"Address": "10.138.0.5",
"CreateIndex": 6,
2017-05-26 23:17:07 +00:00
"Datacenter": "dc1",
"Drain": false,
"Drivers": {
"java": {
"Attributes": {
"driver.java.runtime": "OpenJDK Runtime Environment (build 1.8.0_162-8u162-b12-1~deb9u1-b12)",
"driver.java.vm": "OpenJDK 64-Bit Server VM (build 25.162-b12, mixed mode)",
"driver.java.version": "openjdk version \"1.8.0_162"
},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.781948669Z"
},
"qemu": {
"Attributes": null,
"Detected": false,
"HealthDescription": "",
"Healthy": false,
"UpdateTime": "2018-04-11T23:33:48.7819898Z"
},
"rkt": {
"Attributes": {
"driver.rkt.appc.version": "0.8.11",
"driver.rkt.volumes.enabled": "1",
"driver.rkt.version": "1.29.0"
},
"Detected": true,
"HealthDescription": "Driver rkt is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.81079772Z"
},
"docker": {
"Attributes": {
"driver.docker.bridge_ip": "172.17.0.1",
"driver.docker.version": "18.03.0-ce",
"driver.docker.volumes.enabled": "1"
},
"Detected": true,
"HealthDescription": "Driver is available and responsive",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.713720323Z"
},
"exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "Driver exec is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.711026521Z"
},
"raw_exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.710448534Z"
}
},
2018-04-12 18:34:01 +00:00
"ID": "f7476465-4d6e-c0de-26d0-e383c49be941",
"ModifyIndex": 2526,
"Name": "nomad-4",
"NodeClass": "",
"SchedulingEligibility": "eligible",
2017-05-26 23:17:07 +00:00
"Status": "ready",
"StatusDescription": "",
2018-04-12 18:34:01 +00:00
"Version": "0.8.0-rc1"
2017-05-26 23:17:07 +00:00
}
]
```
## 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
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
2017-05-26 23:17:07 +00:00
[required ACLs](/api/index.html#acls).
2017-09-15 03:59:18 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ----------------- |
| `YES` | `node:read` |
2017-05-26 23:17:07 +00:00
### Parameters
- `:node_id` `(string: <required>)`- 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 \
2018-04-12 18:34:01 +00:00
http://localhost:4646/v1/node/f7476465-4d6e-c0de-26d0-e383c49be941
2017-05-26 23:17:07 +00:00
```
### Sample Response
```json
{
"Attributes": {
2018-04-12 18:34:01 +00:00
"driver.rkt": "1",
"driver.docker.bridge_ip": "172.17.0.1",
"unique.storage.volume": "/dev/sda1",
"driver.exec": "1",
"driver.rkt.volumes.enabled": "1",
"os.signals": "SIGSTOP,SIGTTIN,SIGWINCH,SIGXCPU,SIGXFSZ,SIGIO,SIGKILL,SIGTTOU,SIGINT,SIGHUP,SIGTRAP,SIGALRM,SIGPIPE,SIGURG,SIGABRT,SIGSEGV,SIGIOT,SIGTERM,SIGBUS,SIGPROF,SIGQUIT,SIGTSTP,SIGUSR2,SIGFPE,SIGCONT,SIGILL,SIGSYS,SIGUSR1,SIGCHLD",
"cpu.totalcompute": "2200",
"driver.raw_exec": "1",
"driver.java.version": "openjdk version \"1.8.0_162",
"kernel.name": "linux",
"unique.cgroup.mountpoint": "/sys/fs/cgroup",
2017-05-26 23:17:07 +00:00
"driver.docker.volumes.enabled": "1",
2018-04-12 18:34:01 +00:00
"cpu.frequency": "2200",
"consul.datacenter": "dc1",
"unique.storage.bytestotal": "31637520384",
"unique.network.ip-address": "10.138.0.5",
"os.version": "9.4",
"unique.hostname": "nomad-4",
"driver.rkt.version": "1.29.0",
"driver.java.vm": "OpenJDK 64-Bit Server VM (build 25.162-b12, mixed mode)",
"consul.server": "false",
"kernel.version": "4.9.0-6-amd64",
"cpu.numcores": "1",
"driver.docker.version": "18.03.0-ce",
"unique.consul.name": "nomad-4",
"driver.java": "1",
"consul.revision": "9a494b5f+CHANGES",
"os.name": "debian",
"consul.version": "1.0.6",
"driver.java.runtime": "OpenJDK Runtime Environment (build 1.8.0_162-8u162-b12-1~deb9u1-b12)",
"nomad.version": "0.8.0-rc1",
"memory.totalbytes": "3883982848",
"unique.storage.bytesfree": "26626150400",
2017-05-26 23:17:07 +00:00
"driver.docker": "1",
2018-04-12 18:34:01 +00:00
"cpu.modelname": "Intel(R) Xeon(R) CPU @ 2.20GHz",
2017-05-26 23:17:07 +00:00
"cpu.arch": "amd64",
2018-04-12 18:34:01 +00:00
"driver.rkt.appc.version": "0.8.11"
},
"ComputedClass": "v1:1652208824869124256",
"CreateIndex": 6,
"Datacenter": "dc1",
"Drain": false,
"DrainStrategy": null,
"Drivers": {
"java": {
"Attributes": {
"driver.java.runtime": "OpenJDK Runtime Environment (build 1.8.0_162-8u162-b12-1~deb9u1-b12)",
"driver.java.vm": "OpenJDK 64-Bit Server VM (build 25.162-b12, mixed mode)",
"driver.java.version": "openjdk version \"1.8.0_162"
},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.781948669Z"
},
"qemu": {
"Attributes": null,
"Detected": false,
"HealthDescription": "",
"Healthy": false,
"UpdateTime": "2018-04-11T23:33:48.7819898Z"
},
"rkt": {
"Attributes": {
"driver.rkt.appc.version": "0.8.11",
"driver.rkt.volumes.enabled": "1",
"driver.rkt.version": "1.29.0"
},
"Detected": true,
"HealthDescription": "Driver rkt is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.81079772Z"
},
"docker": {
"Attributes": {
"driver.docker.bridge_ip": "172.17.0.1",
"driver.docker.version": "18.03.0-ce",
"driver.docker.volumes.enabled": "1"
},
"Detected": true,
"HealthDescription": "Driver is available and responsive",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.713720323Z"
},
"exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "Driver exec is detected: true",
"Healthy": true,
"UpdateTime": "2018-04-11T23:34:48.711026521Z"
},
"raw_exec": {
"Attributes": {},
"Detected": true,
"HealthDescription": "",
"Healthy": true,
"UpdateTime": "2018-04-11T23:33:48.710448534Z"
}
},
"Events": [
{
"CreateIndex": 0,
"Details": null,
2018-05-12 00:26:25 +00:00
"Message": "Node registered",
2018-04-12 18:34:01 +00:00
"Subsystem": "Cluster",
"Timestamp": "2018-04-10T23:43:17Z"
}
],
"HTTPAddr": "10.138.0.5:4646",
"ID": "f7476465-4d6e-c0de-26d0-e383c49be941",
"Links": {
"consul": "dc1.nomad-4"
},
"Meta": null,
"ModifyIndex": 2526,
"Name": "nomad-4",
"NodeClass": "",
"Reserved": {
"CPU": 0,
"DiskMB": 0,
"IOPS": 0,
"MemoryMB": 0,
"Networks": null
2017-05-26 23:17:07 +00:00
},
"Resources": {
2018-04-12 18:34:01 +00:00
"CPU": 2200,
"DiskMB": 25392,
2017-05-26 23:17:07 +00:00
"IOPS": 0,
2018-04-12 18:34:01 +00:00
"MemoryMB": 3704,
2017-05-26 23:17:07 +00:00
"Networks": [
{
2018-04-12 18:34:01 +00:00
"CIDR": "10.138.0.5/32",
"Device": "eth0",
"DynamicPorts": null,
"IP": "10.138.0.5",
2017-05-26 23:17:07 +00:00
"MBits": 1000,
2018-04-12 18:34:01 +00:00
"ReservedPorts": null
2017-05-26 23:17:07 +00:00
}
]
},
2018-04-12 18:34:01 +00:00
"SchedulingEligibility": "eligible",
"SecretID": "",
2017-05-26 23:17:07 +00:00
"Status": "ready",
"StatusDescription": "",
2018-04-12 18:34:01 +00:00
"StatusUpdatedAt": 1523552938,
"TLSEnabled": false
2017-05-26 23:17:07 +00:00
}
```
## List Node Allocations
This endpoint lists all of the allocations for the given node. This can be used to
determine what allocations have been scheduled on the node, their current status,
and the values of dynamically assigned resources, like ports.
| Method | Path | Produces |
| ------- | ------------------------------- | -------------------------- |
| `GET` | `/v1/node/:node_id/allocations` | `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).
2017-09-15 04:42:19 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------------------------ |
| `YES` | `node:read,namespace:read-job` |
### Parameters
- `:node_id` `(string: <required>)`- 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 \
2018-04-12 18:34:01 +00:00
http://localhost:4646/v1/node/e02b6169-83bd-9df6-69bd-832765f333eb/allocations
```
### Sample Response
2017-08-07 21:34:18 +00:00
```json
[
{
2018-04-12 18:34:01 +00:00
"AllocModifyIndex": 2555,
"ClientDescription": "",
"ClientStatus": "running",
"CreateIndex": 2555,
"CreateTime": 1523490066575461000,
"DeploymentID": "",
"DeploymentStatus": {
"Healthy": true,
"ModifyIndex": 0
},
"DesiredDescription": "",
"DesiredStatus": "run",
"DesiredTransition": {
"Migrate": null
},
"EvalID": "5129bc74-9785-c39a-08da-bddc8aa778b1",
"FollowupEvalID": "",
"ID": "fefe81d0-08b2-4eca-fae6-6560cde46d31",
"Job": {
"AllAtOnce": false,
2018-04-12 18:34:01 +00:00
"Constraints": null,
"CreateIndex": 2553,
"Datacenters": [
"dc1"
],
2018-04-12 18:34:01 +00:00
"ID": "webapp",
"JobModifyIndex": 2553,
"Meta": null,
"ModifyIndex": 2554,
"Name": "webapp",
"Namespace": "default",
"ParameterizedJob": null,
"ParentID": "",
"Payload": null,
"Periodic": null,
"Priority": 50,
"Region": "global",
"Stable": false,
"Status": "pending",
"StatusDescription": "",
"Stop": false,
"SubmitTime": 1523490066563405000,
"TaskGroups": [
{
2018-04-12 18:34:01 +00:00
"Constraints": null,
"Count": 9,
"EphemeralDisk": {
"Migrate": false,
"SizeMB": 300,
"Sticky": false
},
"Meta": null,
"Migrate": {
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
2018-04-12 18:34:01 +00:00
"MaxParallel": 2,
"MinHealthyTime": 15000000000
},
"Name": "webapp",
"ReschedulePolicy": {
"Attempts": 0,
"Delay": 30000000000,
"DelayFunction": "exponential",
"Interval": 0,
"MaxDelay": 3600000000000,
"Unlimited": true
},
"RestartPolicy": {
2018-04-12 18:34:01 +00:00
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"Tasks": [
{
2018-04-12 18:34:01 +00:00
"Artifacts": null,
"Config": {
2018-04-12 18:34:01 +00:00
"args": [
"-text",
"ok4"
],
"image": "hashicorp/http-echo:0.2.3",
"port_map": [
{
2018-04-12 18:34:01 +00:00
"http": 5678
}
]
},
"Constraints": null,
2018-04-12 18:34:01 +00:00
"DispatchPayload": null,
"Driver": "docker",
"Env": null,
"KillSignal": "",
"KillTimeout": 5000000000,
"Leader": false,
"LogConfig": {
"MaxFileSizeMB": 10,
"MaxFiles": 10
},
"Meta": null,
"Name": "webapp",
"Resources": {
2018-04-12 18:34:01 +00:00
"CPU": 100,
"DiskMB": 0,
"IOPS": 0,
2018-04-12 18:34:01 +00:00
"MemoryMB": 300,
"Networks": [
{
"CIDR": "",
2018-04-12 18:34:01 +00:00
"Device": "",
"DynamicPorts": [
{
2018-04-12 18:34:01 +00:00
"Label": "http",
"Value": 0
}
2018-04-12 18:34:01 +00:00
],
"IP": "",
"MBits": 10,
"ReservedPorts": null
}
]
},
2018-04-12 18:34:01 +00:00
"Services": [
{
"AddressMode": "auto",
"Checks": [
{
"AddressMode": "",
"Args": null,
"CheckRestart": null,
"Command": "",
"Header": null,
"InitialStatus": "",
"Interval": 10000000000,
"Method": "",
"Name": "http-ok",
"Path": "/",
"PortLabel": "",
"Protocol": "",
"TLSSkipVerify": false,
"Timeout": 2000000000,
"Type": "http"
}
],
"Name": "webapp",
"PortLabel": "http",
"Tags": null
}
],
"ShutdownDelay": 0,
"Templates": null,
"User": "",
"Vault": null
}
],
2018-04-12 18:34:01 +00:00
"Update": null
}
],
2018-04-12 18:34:01 +00:00
"Type": "service",
"Update": {
2018-04-12 18:34:01 +00:00
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "",
"HealthyDeadline": 0,
2018-04-12 18:34:01 +00:00
"MaxParallel": 0,
"MinHealthyTime": 0,
"Stagger": 0
},
"VaultToken": "",
2018-04-12 18:34:01 +00:00
"Version": 0
},
2018-04-12 18:34:01 +00:00
"JobID": "webapp",
"Metrics": {
"AllocationTime": 63337,
"ClassExhausted": null,
"ClassFiltered": null,
"CoalescedFailures": 0,
"ConstraintFiltered": null,
"DimensionExhausted": null,
"NodesAvailable": {
"dc1": 2
},
"NodesEvaluated": 2,
"NodesExhausted": 0,
"NodesFiltered": 0,
"QuotaExhausted": null,
"Scores": {
"46f1c6c4-a0e5-21f6-fd5c-d76c3d84e806.binpack": 2.6950883117541586,
"f7476465-4d6e-c0de-26d0-e383c49be941.binpack": 2.6950883117541586
}
},
"ModifyIndex": 2567,
"ModifyTime": 1523490089807324000,
"Name": "webapp.webapp[0]",
"Namespace": "default",
"NextAllocation": "",
"NodeID": "f7476465-4d6e-c0de-26d0-e383c49be941",
"PreviousAllocation": "",
"RescheduleTracker": null,
"Resources": {
2018-04-12 18:34:01 +00:00
"CPU": 100,
"DiskMB": 300,
"IOPS": 0,
2018-04-12 18:34:01 +00:00
"MemoryMB": 300,
"Networks": [
{
"CIDR": "",
2018-04-12 18:34:01 +00:00
"Device": "eth0",
"DynamicPorts": [
{
2018-04-12 18:34:01 +00:00
"Label": "http",
"Value": 25920
}
2018-04-12 18:34:01 +00:00
],
"IP": "10.138.0.5",
"MBits": 10,
"ReservedPorts": null
}
]
},
"SharedResources": {
"CPU": 0,
"DiskMB": 300,
"IOPS": 0,
2018-04-12 18:34:01 +00:00
"MemoryMB": 0,
"Networks": null
},
2018-04-12 18:34:01 +00:00
"TaskGroup": "webapp",
"TaskResources": {
2018-04-12 18:34:01 +00:00
"webapp": {
"CPU": 100,
"DiskMB": 0,
"IOPS": 0,
2018-04-12 18:34:01 +00:00
"MemoryMB": 300,
"Networks": [
{
"CIDR": "",
2018-04-12 18:34:01 +00:00
"Device": "eth0",
"DynamicPorts": [
{
2018-04-12 18:34:01 +00:00
"Label": "http",
"Value": 25920
}
2018-04-12 18:34:01 +00:00
],
"IP": "10.138.0.5",
"MBits": 10,
"ReservedPorts": null
}
]
}
},
"TaskStates": {
2018-04-12 18:34:01 +00:00
"webapp": {
"Events": [
{
2018-04-12 18:34:01 +00:00
"Details": {},
"DiskLimit": 0,
"DisplayMessage": "Task received by client",
"DownloadError": "",
"DriverError": "",
2018-04-12 18:34:01 +00:00
"DriverMessage": "",
"ExitCode": 0,
2018-04-12 18:34:01 +00:00
"FailedSibling": "",
"FailsTask": false,
"GenericSource": "",
"KillError": "",
"KillReason": "",
2018-04-12 18:34:01 +00:00
"KillTimeout": 0,
"Message": "",
"RestartReason": "",
"SetupError": "",
"Signal": 0,
"StartDelay": 0,
"TaskSignal": "",
2018-04-12 18:34:01 +00:00
"TaskSignalReason": "",
"Time": 1523490066712543500,
"Type": "Received",
"ValidationError": "",
"VaultError": ""
},
{
2018-04-12 18:34:01 +00:00
"Details": {
"message": "Building Task Directory"
},
"DiskLimit": 0,
"DisplayMessage": "Building Task Directory",
"DownloadError": "",
"DriverError": "",
2018-04-12 18:34:01 +00:00
"DriverMessage": "",
"ExitCode": 0,
2018-04-12 18:34:01 +00:00
"FailedSibling": "",
"FailsTask": false,
"GenericSource": "",
"KillError": "",
"KillReason": "",
2018-04-12 18:34:01 +00:00
"KillTimeout": 0,
"Message": "Building Task Directory",
"RestartReason": "",
"SetupError": "",
"Signal": 0,
"StartDelay": 0,
"TaskSignal": "",
2018-04-12 18:34:01 +00:00
"TaskSignalReason": "",
"Time": 1523490066715208000,
"Type": "Task Setup",
"ValidationError": "",
"VaultError": ""
},
{
2018-04-12 18:34:01 +00:00
"Details": {},
"DiskLimit": 0,
"DisplayMessage": "Task started by client",
"DownloadError": "",
"DriverError": "",
2018-04-12 18:34:01 +00:00
"DriverMessage": "",
"ExitCode": 0,
2018-04-12 18:34:01 +00:00
"FailedSibling": "",
"FailsTask": false,
"GenericSource": "",
"KillError": "",
"KillReason": "",
2018-04-12 18:34:01 +00:00
"KillTimeout": 0,
"Message": "",
"RestartReason": "",
"SetupError": "",
"Signal": 0,
"StartDelay": 0,
"TaskSignal": "",
2018-04-12 18:34:01 +00:00
"TaskSignalReason": "",
"Time": 1523490068433051100,
"Type": "Started",
"ValidationError": "",
"VaultError": ""
}
2018-04-12 18:34:01 +00:00
],
"Failed": false,
"FinishedAt": "0001-01-01T00:00:00Z",
"LastRestart": "0001-01-01T00:00:00Z",
"Restarts": 0,
"StartedAt": "2018-04-11T23:41:08.445128764Z",
"State": "running"
}
2018-04-12 18:34:01 +00:00
}
}
]
```
2017-05-26 23:17:07 +00:00
## 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
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
2017-05-26 23:17:07 +00:00
[required ACLs](/api/index.html#acls).
2017-09-15 03:41:44 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------------ |
| `NO` | `node:write` |
2017-05-26 23:17:07 +00:00
### Parameters
- `:node_id` `(string: <required>)`- 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 \
2018-04-12 18:34:01 +00:00
http://localhost:4646/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/evaluate
2017-05-26 23:17:07 +00:00
```
### Sample Response
```json
{
2018-04-12 18:34:01 +00:00
"EvalCreateIndex": 3671,
2017-05-26 23:17:07 +00:00
"EvalIDs": [
2018-04-12 18:34:01 +00:00
"4dfc2db7-b481-c53b-3072-14479aa44be3"
2017-05-26 23:17:07 +00:00
],
2018-04-12 18:34:01 +00:00
"HeartbeatTTL": 0,
"Index": 3671,
"KnownLeader": false,
"LastContact": 0,
"LeaderRPCAddr": "10.138.0.2:4647",
2017-05-26 23:17:07 +00:00
"NodeModifyIndex": 0,
2018-04-12 18:34:01 +00:00
"NumNodes": 3,
2017-05-26 23:17:07 +00:00
"Servers": [
{
2018-04-12 18:34:01 +00:00
"Datacenter": "dc1",
"RPCAdvertiseAddr": "10.138.0.2:4647",
2017-05-26 23:17:07 +00:00
"RPCMajorVersion": 1,
2018-04-12 18:34:01 +00:00
"RPCMinorVersion": 1
},
{
"Datacenter": "dc1",
"RPCAdvertiseAddr": "10.138.0.3:4647",
"RPCMajorVersion": 1,
"RPCMinorVersion": 1
},
{
"Datacenter": "dc1",
"RPCAdvertiseAddr": "10.138.0.4:4647",
"RPCMajorVersion": 1,
"RPCMinorVersion": 1
2017-05-26 23:17:07 +00:00
}
2018-04-12 18:34:01 +00:00
]
2017-05-26 23:17:07 +00:00
}
2018-04-12 18:34:01 +00:00
2017-05-26 23:17:07 +00:00
```
## 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
2018-04-12 18:34:01 +00:00
be migrated to new nodes. See the [Decommissioning Nodes
guide](/guides/node-draining.html) for suggested usage.
2017-05-26 23:17:07 +00:00
| Method | Path | Produces |
| ------- | ------------------------- | -------------------------- |
| `POST` | `/v1/node/:node_id/drain` | `application/json` |
The table below shows this endpoint's support for
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
2017-05-26 23:17:07 +00:00
[required ACLs](/api/index.html#acls).
2017-09-15 03:33:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------------ |
| `NO` | `node:write` |
2017-05-26 23:17:07 +00:00
### Parameters
- `:node_id` `(string: <required>)`- 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.
2018-04-12 18:34:01 +00:00
- `DrainSpec` `(object: <optional>)` - Specifies if drain mode should be
enabled. A missing or null value disables an existing drain.
- `Deadline` `(int: <required>)` - Specifies how long to wait in nanoseconds
for allocations to finish migrating before they are force stopped. This is
also how long batch jobs are given to complete before being migrated.
- `IgnoreSystemJobs` `(bool: false)` - Specifies whether or not to stop system
jobs as part of a drain. By default system jobs will be stopped after all
other allocations have migrated or the deadline is reached. Setting this to
`true` means system jobs are always left running.
- `MarkEligible` `(bool: false)` - Specifies whether to mark a node as eligible
for scheduling again when _disabling_ a drain.
### Sample Payload
```json
{
"DrainSpec": {
"Deadline": "3600000000000",
"IgnoreSystemJobs": true
}
}
```
2017-05-26 23:17:07 +00:00
### Sample Request
```text
$ curl \
2018-04-12 18:34:01 +00:00
-XPOST \
--data @drain.json \
http://localhost:4646/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/drain
2017-05-26 23:17:07 +00:00
```
### Sample Response
```json
{
2018-04-12 18:34:01 +00:00
"EvalCreateIndex": 0,
"EvalIDs": null,
"Index": 3742,
"NodeModifyIndex": 3742
2017-05-26 23:17:07 +00:00
}
```
2017-10-26 21:18:34 +00:00
## Purge Node
This endpoint purges a node from the system. Nodes can still join the cluster if
they are alive.
| Method | Path | Produces |
| ------- | ------------------------- | -------------------------- |
| `POST` | `/v1/node/:node_id/purge` | `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` | `node:write` |
### Parameters
- `:node_id` `(string: <required>)`- 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 \
2018-04-12 18:34:01 +00:00
-XPOST http://localhost:4646/v1/node/f7476465-4d6e-c0de-26d0-e383c49be941/purge
2017-10-26 21:18:34 +00:00
```
### Sample Response
```json
{
2018-04-12 18:34:01 +00:00
"EvalCreateIndex": 3817,
2017-10-26 21:18:34 +00:00
"EvalIDs": [
2018-04-12 18:34:01 +00:00
"71bad787-5ab1-9939-be02-4809441583cd"
2017-10-26 21:18:34 +00:00
],
2018-04-12 18:34:01 +00:00
"HeartbeatTTL": 0,
"Index": 3816,
"KnownLeader": false,
2017-10-26 21:18:34 +00:00
"LastContact": 0,
2018-04-12 18:34:01 +00:00
"LeaderRPCAddr": "",
"NodeModifyIndex": 3816,
"NumNodes": 0,
"Servers": null
2017-10-26 21:18:34 +00:00
}
```
2018-03-23 21:12:19 +00:00
#### Field Reference
- Events - A list of the last 10 node events for this node. A node event is a
high level concept of noteworthy events for a node.
Each node event has the following fields:
- `Message` - The specific message for the event, detailing what occurred.
- `Subsystem` - The subsystem where the node event took place. Subsysystems
include:
- `Drain` - The Nomad server draining subsystem.
2018-03-23 21:12:19 +00:00
- `Driver` - The Nomad client driver subsystem.
2018-03-23 21:12:19 +00:00
- `Heartbeat` - Either Nomad client or server heartbeating subsystem.
2018-03-23 21:12:19 +00:00
- `Cluster` - Nomad server cluster management subsystem.
2018-03-23 21:12:19 +00:00
- `Details` - Any further details about the event, formatted as a key/value
pair.
- `Timestamp` - Each node event has an ISO 8601 timestamp.
2018-03-23 21:12:19 +00:00
- `CreateIndex` - The Raft index at which the event was committed.