github.com/quite/nomad@v0.8.6/website/source/api/agent.html.md (about) 1 --- 2 layout: api 3 page_title: Agent - HTTP API 4 sidebar_current: api-agent 5 description: |- 6 The /agent endpoints interact with the local Nomad agent to interact with 7 members and servers. 8 --- 9 10 # Agent HTTP API 11 12 The `/agent` endpoints are used to interact with the local Nomad agent. 13 14 ## List Members 15 16 This endpoint queries the agent for the known peers in the gossip pool. This 17 endpoint is only applicable to servers. Due to the nature of gossip, this is 18 eventually consistent. 19 20 | Method | Path | Produces | 21 | ------ | ---------------------------- | -------------------------- | 22 | `GET` | `/agent/members` | `application/json` | 23 24 The table below shows this endpoint's support for 25 [blocking queries](/api/index.html#blocking-queries) and 26 [required ACLs](/api/index.html#acls). 27 28 | Blocking Queries | ACL Required | 29 | ---------------- | ------------ | 30 | `NO` | `node:read` | 31 32 ### Sample Request 33 34 ```text 35 $ curl \ 36 https://localhost:4646/v1/agent/members 37 ``` 38 39 ### Sample Response 40 41 ```json 42 { 43 "ServerName": "bacon-mac", 44 "ServerRegion": "global", 45 "ServerDC": "dc1", 46 "Members": [ 47 { 48 "Name": "bacon-mac.global", 49 "Addr": "127.0.0.1", 50 "Port": 4648, 51 "Tags": { 52 "mvn": "1", 53 "build": "0.5.5dev", 54 "port": "4647", 55 "bootstrap": "1", 56 "role": "nomad", 57 "region": "global", 58 "dc": "dc1", 59 "vsn": "1" 60 }, 61 "Status": "alive", 62 "ProtocolMin": 1, 63 "ProtocolMax": 5, 64 "ProtocolCur": 2, 65 "DelegateMin": 2, 66 "DelegateMax": 4, 67 "DelegateCur": 4 68 } 69 ] 70 } 71 ``` 72 73 ## List Servers 74 75 This endpoint lists the known server nodes. The `servers` endpoint is used to 76 query an agent in client mode for its list of known servers. Client nodes 77 register themselves with these server addresses so that they may dequeue work. 78 The servers endpoint can be used to keep this configuration up to date if there 79 are changes in the cluster. 80 81 | Method | Path | Produces | 82 | ------ | ---------------------------- | -------------------------- | 83 | `GET` | `/agent/servers` | `application/json` | 84 85 The table below shows this endpoint's support for 86 [blocking queries](/api/index.html#blocking-queries) and 87 [required ACLs](/api/index.html#acls). 88 89 | Blocking Queries | ACL Required | 90 | ---------------- | ------------ | 91 | `NO` | `agent:read` | 92 93 ### Sample Request 94 95 ```text 96 $ curl \ 97 https://localhost:4646/v1/agent/servers 98 ``` 99 100 ### Sample Response 101 102 ```json 103 [ 104 "127.0.0.1:4647" 105 ] 106 ``` 107 108 ## Update Servers 109 110 This endpoint updates the list of known servers to the provided list. This 111 **replaces** all previous server addresses with the new list. 112 113 | Method | Path | Produces | 114 | ------ | ---------------------------- | -------------------------- | 115 | `POST` | `/agent/servers` | `(empty body)` | 116 117 The table below shows this endpoint's support for 118 [blocking queries](/api/index.html#blocking-queries) and 119 [required ACLs](/api/index.html#acls). 120 121 | Blocking Queries | ACL Required | 122 | ---------------- | ------------- | 123 | `NO` | `agent:write` | 124 125 ### Parameters 126 127 - `address` `(string: <required>)` - Specifies the list of addresses in the 128 format `ip:port`. This is specified as a query string! 129 130 ### Sample Request 131 132 ```text 133 $ curl \ 134 --request POST \ 135 https://localhost:4646/v1/agent/servers?address=1.2.3.4:4647&address=5.6.7.8:4647 136 ``` 137 138 ## Query Self 139 140 This endpoint queries the state of the target agent (self). 141 142 | Method | Path | Produces | 143 | ------ | ---------------------------- | -------------------------- | 144 | `GET` | `/agent/self` | `application/json` | 145 146 The table below shows this endpoint's support for 147 [blocking queries](/api/index.html#blocking-queries) and 148 [required ACLs](/api/index.html#acls). 149 150 | Blocking Queries | ACL Required | 151 | ---------------- | ------------ | 152 | `NO` | `agent:read` | 153 154 ### Sample Request 155 156 ```text 157 $ curl \ 158 https://localhost:4646/v1/agent/self 159 ``` 160 161 ### Sample Response 162 163 ```json 164 { 165 "config": { 166 "Addresses": { 167 "HTTP": "127.0.0.1", 168 "RPC": "127.0.0.1", 169 "Serf": "127.0.0.1" 170 }, 171 "AdvertiseAddrs": { 172 "HTTP": "127.0.0.1:4646", 173 "RPC": "127.0.0.1:4647", 174 "Serf": "127.0.0.1:4648" 175 }, 176 "BindAddr": "127.0.0.1", 177 "Client": { 178 "AllocDir": "", 179 "ChrootEnv": {}, 180 "ClientMaxPort": 14512, 181 "ClientMinPort": 14000, 182 "Enabled": true, 183 "GCDiskUsageThreshold": 99, 184 "GCInodeUsageThreshold": 99, 185 "GCInterval": 600000000000, 186 "MaxKillTimeout": "30s", 187 "Meta": {}, 188 "NetworkInterface": "lo0", 189 "NetworkSpeed": 0, 190 "NodeClass": "", 191 "Options": { 192 "driver.docker.volumes": "true" 193 }, 194 "Reserved": { 195 "CPU": 0, 196 "DiskMB": 0, 197 "IOPS": 0, 198 "MemoryMB": 0, 199 "ParsedReservedPorts": null, 200 "ReservedPorts": "" 201 }, 202 "Servers": null, 203 "StateDir": "" 204 }, 205 "Consul": { 206 "Addr": "", 207 "Auth": "", 208 "AutoAdvertise": true, 209 "CAFile": "", 210 "CertFile": "", 211 "ChecksUseAdvertise": false, 212 "ClientAutoJoin": true, 213 "ClientServiceName": "nomad-client", 214 "EnableSSL": false, 215 "KeyFile": "", 216 "ServerAutoJoin": true, 217 "ServerServiceName": "nomad", 218 "Timeout": 5000000000, 219 "Token": "", 220 "VerifySSL": false 221 }, 222 "DataDir": "", 223 "Datacenter": "dc1", 224 "DevMode": true, 225 "DisableAnonymousSignature": true, 226 "DisableUpdateCheck": false, 227 "EnableDebug": true, 228 "EnableSyslog": false, 229 "Files": null, 230 "HTTPAPIResponseHeaders": {}, 231 "LeaveOnInt": false, 232 "LeaveOnTerm": false, 233 "LogLevel": "DEBUG", 234 "NodeName": "", 235 "Ports": { 236 "HTTP": 4646, 237 "RPC": 4647, 238 "Serf": 4648 239 }, 240 "Region": "global", 241 "Revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9", 242 "Server": { 243 "BootstrapExpect": 0, 244 "DataDir": "", 245 "Enabled": true, 246 "EnabledSchedulers": null, 247 "HeartbeatGrace": "", 248 "NodeGCThreshold": "", 249 "NumSchedulers": 0, 250 "ProtocolVersion": 0, 251 "RejoinAfterLeave": false, 252 "RetryInterval": "30s", 253 "RetryJoin": [], 254 "RetryMaxAttempts": 0, 255 "StartJoin": [] 256 }, 257 "SyslogFacility": "LOCAL0", 258 "TLSConfig": { 259 "CAFile": "", 260 "CertFile": "", 261 "EnableHTTP": false, 262 "EnableRPC": false, 263 "KeyFile": "", 264 "VerifyServerHostname": false 265 }, 266 "Telemetry": { 267 "CirconusAPIApp": "", 268 "CirconusAPIToken": "", 269 "CirconusAPIURL": "", 270 "CirconusBrokerID": "", 271 "CirconusBrokerSelectTag": "", 272 "CirconusCheckDisplayName": "", 273 "CirconusCheckForceMetricActivation": "", 274 "CirconusCheckID": "", 275 "CirconusCheckInstanceID": "", 276 "CirconusCheckSearchTag": "", 277 "CirconusCheckSubmissionURL": "", 278 "CirconusCheckTags": "", 279 "CirconusSubmissionInterval": "", 280 "CollectionInterval": "1s", 281 "DataDogAddr": "", 282 "DataDogTags": [], 283 "DisableHostname": false, 284 "PublishAllocationMetrics": false, 285 "PublishNodeMetrics": false, 286 "StatsdAddr": "", 287 "StatsiteAddr": "", 288 "UseNodeName": false 289 }, 290 "Vault": { 291 "Addr": "https://vault.service.consul:8200", 292 "AllowUnauthenticated": true, 293 "ConnectionRetryIntv": 30000000000, 294 "Enabled": null, 295 "Role": "", 296 "TLSCaFile": "", 297 "TLSCaPath": "", 298 "TLSCertFile": "", 299 "TLSKeyFile": "", 300 "TLSServerName": "", 301 "TLSSkipVerify": null, 302 "TaskTokenTTL": "", 303 "Token": "root" 304 }, 305 "Version": "0.5.5", 306 "VersionPrerelease": "dev" 307 }, 308 "member": { 309 "Addr": "127.0.0.1", 310 "DelegateCur": 4, 311 "DelegateMax": 4, 312 "DelegateMin": 2, 313 "Name": "bacon-mac.global", 314 "Port": 4648, 315 "ProtocolCur": 2, 316 "ProtocolMax": 5, 317 "ProtocolMin": 1, 318 "Status": "alive", 319 "Tags": { 320 "role": "nomad", 321 "region": "global", 322 "dc": "dc1", 323 "vsn": "1", 324 "mvn": "1", 325 "build": "0.5.5dev", 326 "port": "4647", 327 "bootstrap": "1" 328 } 329 }, 330 "stats": { 331 "runtime": { 332 "cpu_count": "8", 333 "kernel.name": "darwin", 334 "arch": "amd64", 335 "version": "go1.8", 336 "max_procs": "7", 337 "goroutines": "79" 338 }, 339 "nomad": { 340 "server": "true", 341 "leader": "true", 342 "leader_addr": "127.0.0.1:4647", 343 "bootstrap": "false", 344 "known_regions": "1" 345 }, 346 "raft": { 347 "num_peers": "0", 348 "fsm_pending": "0", 349 "last_snapshot_index": "0", 350 "last_log_term": "2", 351 "commit_index": "144", 352 "term": "2", 353 "last_log_index": "144", 354 "protocol_version_max": "3", 355 "snapshot_version_max": "1", 356 "latest_configuration_index": "1", 357 "latest_configuration": "[{Suffrage:Voter ID:127.0.0.1:4647 Address:127.0.0.1:4647}]", 358 "last_contact": "never", 359 "applied_index": "144", 360 "protocol_version": "1", 361 "protocol_version_min": "0", 362 "snapshot_version_min": "0", 363 "state": "Leader", 364 "last_snapshot_term": "0" 365 }, 366 "client": { 367 "heartbeat_ttl": "17.79568937s", 368 "node_id": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 369 "known_servers": "127.0.0.1:4647", 370 "num_allocations": "0", 371 "last_heartbeat": "10.107423052s" 372 }, 373 "serf": { 374 "event_time": "1", 375 "event_queue": "0", 376 "encrypted": "false", 377 "member_time": "1", 378 "query_time": "1", 379 "intent_queue": "0", 380 "query_queue": "0", 381 "members": "1", 382 "failed": "0", 383 "left": "0", 384 "health_score": "0" 385 } 386 } 387 } 388 ``` 389 390 ## Join Agent 391 392 This endpoint introduces a new member to the gossip pool. This endpoint is only 393 eligible for servers. 394 395 | Method | Path | Produces | 396 | ------ | ---------------------------- | -------------------------- | 397 | `POST` | `/agent/join` | `application/json` | 398 399 The table below shows this endpoint's support for 400 [blocking queries](/api/index.html#blocking-queries) and 401 [required ACLs](/api/index.html#acls). 402 403 | Blocking Queries | ACL Required | 404 | ---------------- | ------------ | 405 | `NO` | `none` | 406 407 ### Parameters 408 409 - `address` `(string: <required>)` - Specifies the address to join in the 410 `ip:port` format. This is provided as a query parameter and may be specified 411 multiple times to join multiple servers. 412 413 ### Sample Request 414 415 ```text 416 $ curl \ 417 --request POST \ 418 https://localhost:4646/v1/agent/join?address=1.2.3.4&address=5.6.7.8 419 ``` 420 421 ### Sample Response 422 423 ```json 424 { 425 "error": "", 426 "num_joined": 2 427 } 428 ``` 429 430 ## Force Leave Agent 431 432 This endpoint forces a member of the gossip pool from the `"failed"` state to 433 the `"left"` state. This allows the consensus protocol to remove the peer and 434 stop attempting replication. This is only applicable for servers. 435 436 | Method | Path | Produces | 437 | ------ | ---------------------------- | -------------------------- | 438 | `POST` | `/agent/force-leave` | `application/json` | 439 440 The table below shows this endpoint's support for 441 [blocking queries](/api/index.html#blocking-queries) and 442 [required ACLs](/api/index.html#acls). 443 444 | Blocking Queries | ACL Required | 445 | ---------------- | ------------- | 446 | `NO` | `agent:write` | 447 448 ### Parameters 449 450 - `node` `(string: <required>)` - Specifies the name of the node to force leave. 451 452 ### Sample Request 453 454 ```text 455 $ curl \ 456 --request POST \ 457 https://localhost:4646/v1/agent/force-leave?node=client-ab2e23dc 458 ``` 459 460 ## Health 461 462 This endpoint returns whether or not the agent is healthy. When using Consul it 463 is the endpoint Nomad will register for its own health checks. 464 465 When the agent is unhealthy 500 will be returned along with JSON response 466 containing an error message. 467 468 | Method | Path | Produces | 469 | ------ | ---------------------------- | -------------------------- | 470 | `GET` | `/agent/health` | `application/json` | 471 472 The table below shows this endpoint's support for 473 [blocking queries](/api/index.html#blocking-queries) and 474 [required ACLs](/api/index.html#acls). 475 476 | Blocking Queries | ACL Required | 477 | ---------------- | ------------ | 478 | `NO` | `none` | 479 480 ### Sample Request 481 482 ```text 483 $ curl \ 484 https://localhost:4646/v1/agent/health 485 ``` 486 487 ### Sample Response 488 489 ```json 490 { 491 "client": { 492 "message": "ok", 493 "ok": true 494 }, 495 "server": { 496 "message": "ok", 497 "ok": true 498 } 499 } 500 ```