github.com/quite/nomad@v0.8.6/website/source/api/client.html.md (about) 1 --- 2 layout: api 3 page_title: Client - HTTP API 4 sidebar_current: api-client 5 description: |- 6 The /client endpoints are used to access client statistics and inspect 7 allocations running on a particular client. 8 --- 9 10 # Client HTTP API 11 12 The `/client` endpoints are used to interact with the Nomad clients. 13 14 Since Nomad 0.8.0, both a client and server can handle client endpoints. This is 15 particularly useful for when a direct connection to a client is not possible due 16 to the network configuration. For high volume access to the client endpoints, 17 particularly endpoints streaming file contents, direct access to the node should 18 be preferred as it avoids adding additional load to the servers. 19 20 When accessing the endpoints via the server, if the desired node is ambiguous 21 based on the URL, an additional `?node_id` query parameter must be provided to 22 disambiguate. 23 24 ## Read Stats 25 26 This endpoint queries the actual resources consumed on a node. The API endpoint 27 is hosted by the Nomad client and requests have to be made to the nomad client 28 whose resource usage metrics are of interest. 29 30 | Method | Path | Produces | 31 | ------ | ---------------------------- | -------------------------- | 32 | `GET` | `/client/stats` | `application/json` | 33 34 The table below shows this endpoint's support for 35 [blocking queries](/api/index.html#blocking-queries) and 36 [required ACLs](/api/index.html#acls). 37 38 | Blocking Queries | ACL Required | 39 | ---------------- | ------------ | 40 | `NO` | `node:read` | 41 42 ### Parameters 43 44 - `node_id` `(string: <optional>)` - Specifies the node to query. This is 45 required when the endpoint is being accessed via a server. This is specified as 46 part of the URL. Note, this must be the _full_ node ID, not the short 47 8-character one. This is specified as part of the path. 48 49 ### Sample Request 50 51 ```text 52 $ curl \ 53 https://localhost:4646/v1/client/stats 54 ``` 55 56 ### Sample Response 57 58 ```json 59 { 60 "AllocDirStats": { 61 "Available": 142943150080, 62 "Device": "", 63 "InodesUsedPercent": 0.05312946180421879, 64 "Mountpoint": "", 65 "Size": 249783500800, 66 "Used": 106578206720, 67 "UsedPercent": 42.668233241448746 68 }, 69 "CPU": [ 70 { 71 "CPU": "cpu0", 72 "Idle": 80, 73 "System": 11, 74 "Total": 20, 75 "User": 9 76 }, 77 { 78 "CPU": "cpu1", 79 "Idle": 99, 80 "System": 0, 81 "Total": 1, 82 "User": 1 83 }, 84 { 85 "CPU": "cpu2", 86 "Idle": 89, 87 "System": 7.000000000000001, 88 "Total": 11, 89 "User": 4 90 }, 91 { 92 "CPU": "cpu3", 93 "Idle": 100, 94 "System": 0, 95 "Total": 0, 96 "User": 0 97 }, 98 { 99 "CPU": "cpu4", 100 "Idle": 92.92929292929293, 101 "System": 4.040404040404041, 102 "Total": 7.07070707070707, 103 "User": 3.0303030303030303 104 }, 105 { 106 "CPU": "cpu5", 107 "Idle": 99, 108 "System": 1, 109 "Total": 1, 110 "User": 0 111 }, 112 { 113 "CPU": "cpu6", 114 "Idle": 92.07920792079209, 115 "System": 4.9504950495049505, 116 "Total": 7.920792079207921, 117 "User": 2.9702970297029703 118 }, 119 { 120 "CPU": "cpu7", 121 "Idle": 99, 122 "System": 0, 123 "Total": 1, 124 "User": 1 125 } 126 ], 127 "CPUTicksConsumed": 1126.8044804480448, 128 "DiskStats": [ 129 { 130 "Available": 142943150080, 131 "Device": "/dev/disk1", 132 "InodesUsedPercent": 0.05312946180421879, 133 "Mountpoint": "/", 134 "Size": 249783500800, 135 "Used": 106578206720, 136 "UsedPercent": 42.668233241448746 137 } 138 ], 139 "Memory": { 140 "Available": 6232244224, 141 "Free": 470618112, 142 "Total": 17179869184, 143 "Used": 10947624960 144 }, 145 "Timestamp": 1495743032992498200, 146 "Uptime": 193520 147 } 148 ``` 149 150 ## Read Allocation Statistics 151 152 The client `allocation` endpoint is used to query the actual resources consumed 153 by an allocation. 154 155 | Method | Path | Produces | 156 | ------ | ------------------------------------ | -------------------------- | 157 | `GET` | `/client/allocation/:alloc_id/stats` | `application/json` | 158 159 The table below shows this endpoint's support for 160 [blocking queries](/api/index.html#blocking-queries) and 161 [required ACLs](/api/index.html#acls). 162 163 | Blocking Queries | ACL Required | 164 | ---------------- | -------------------- | 165 | `NO` | `namespace:read-job` | 166 167 ### Parameters 168 169 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 170 This is specified as part of the URL. Note, this must be the _full_ allocation 171 ID, not the short 8-character one. This is specified as part of the path. 172 173 ### Sample Request 174 175 ```text 176 $ curl \ 177 https://localhost:4646/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/stats 178 ``` 179 180 ### Sample Response 181 182 ```json 183 { 184 "ResourceUsage": { 185 "CpuStats": { 186 "Measured": [ 187 "Throttled Periods", 188 "Throttled Time", 189 "Percent" 190 ], 191 "Percent": 0.14159538847117795, 192 "SystemMode": 0, 193 "ThrottledPeriods": 0, 194 "ThrottledTime": 0, 195 "TotalTicks": 3.256693934837093, 196 "UserMode": 0 197 }, 198 "MemoryStats": { 199 "Cache": 1744896, 200 "KernelMaxUsage": 0, 201 "KernelUsage": 0, 202 "MaxUsage": 4710400, 203 "Measured": [ 204 "RSS", 205 "Cache", 206 "Swap", 207 "Max Usage" 208 ], 209 "RSS": 1486848, 210 "Swap": 0 211 } 212 }, 213 "Tasks": { 214 "redis": { 215 "Pids": null, 216 "ResourceUsage": { 217 "CpuStats": { 218 "Measured": [ 219 "Throttled Periods", 220 "Throttled Time", 221 "Percent" 222 ], 223 "Percent": 0.14159538847117795, 224 "SystemMode": 0, 225 "ThrottledPeriods": 0, 226 "ThrottledTime": 0, 227 "TotalTicks": 3.256693934837093, 228 "UserMode": 0 229 }, 230 "MemoryStats": { 231 "Cache": 1744896, 232 "KernelMaxUsage": 0, 233 "KernelUsage": 0, 234 "MaxUsage": 4710400, 235 "Measured": [ 236 "RSS", 237 "Cache", 238 "Swap", 239 "Max Usage" 240 ], 241 "RSS": 1486848, 242 "Swap": 0 243 } 244 }, 245 "Timestamp": 1495743243970720000 246 } 247 }, 248 "Timestamp": 1495743243970720000 249 } 250 ``` 251 252 ## Read File 253 254 This endpoint reads the contents of a file in an allocation directory. 255 256 | Method | Path | Produces | 257 | ------ | ---------------------------- | -------------------------- | 258 | `GET` | `/client/fs/cat/:alloc_id` | `text/plain` | 259 260 The table below shows this endpoint's support for 261 [blocking queries](/api/index.html#blocking-queries) and 262 [required ACLs](/api/index.html#acls). 263 264 | Blocking Queries | ACL Required | 265 | ---------------- | ------------------- | 266 | `NO` | `namespace:read-fs` | 267 268 ### Parameters 269 270 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 271 This is specified as part of the URL. Note, this must be the _full_ allocation 272 ID, not the short 8-character one. This is specified as part of the path. 273 274 - `path` `(string: "/")` - Specifies the path of the file to read, relative to 275 the root of the allocation directory. 276 277 ### Sample Request 278 279 ```text 280 $ curl \ 281 https://localhost:4646/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99 282 ``` 283 284 ```text 285 $ curl \ 286 https://localhost:4646/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=alloc/file.json 287 ``` 288 289 ### Sample Response 290 291 ```text 292 (whatever was in the file...) 293 ``` 294 295 296 ## Read File at Offset 297 298 This endpoint reads the contents of a file in an allocation directory at a 299 particular offset and limit. 300 301 | Method | Path | Produces | 302 | ------ | ----------------------------- | -------------------------- | 303 | `GET` | `/client/fs/readat/:alloc_id` | `text/plain` | 304 305 The table below shows this endpoint's support for 306 [blocking queries](/api/index.html#blocking-queries) and 307 [required ACLs](/api/index.html#acls). 308 309 | Blocking Queries | ACL Required | 310 | ---------------- | ------------------- | 311 | `NO` | `namespace:read-fs` | 312 313 ### Parameters 314 315 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 316 This is specified as part of the URL. Note, this must be the _full_ allocation 317 ID, not the short 8-character one. This is specified as part of the path. 318 319 - `path` `(string: "/")` - Specifies the path of the file to read, relative to 320 the root of the allocation directory. 321 322 - `offset` `(int: <required>)` - Specifies the byte offset from where content 323 will be read. 324 325 - `limit` `(int: <required>)` - Specifies the number of bytes to read from the 326 offset. 327 328 ### Sample Request 329 330 ```text 331 $ curl \ 332 https://localhost:4646/v1/client/fs/readat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/foo&offset=1323&limit=19303 333 ``` 334 335 ### Sample Response 336 337 ```text 338 (whatever was in the file, starting from offset, up to limit bytes...) 339 ``` 340 341 ## Stream File 342 343 This endpoint streams the contents of a file in an allocation directory. 344 345 | Method | Path | Produces | 346 | ------ | ----------------------------- | -------------------------- | 347 | `GET` | `/client/fs/stream/:alloc_id` | `text/plain` | 348 349 The table below shows this endpoint's support for 350 [blocking queries](/api/index.html#blocking-queries) and 351 [required ACLs](/api/index.html#acls). 352 353 | Blocking Queries | ACL Required | 354 | ---------------- | ------------------- | 355 | `NO` | `namespace:read-fs` | 356 357 ### Parameters 358 359 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 360 This is specified as part of the URL. Note, this must be the _full_ allocation 361 ID, not the short 8-character one. This is specified as part of the path. 362 363 - `path` `(string: "/")` - Specifies the path of the file to read, relative to 364 the root of the allocation directory. 365 366 - `offset` `(int: <required>)` - Specifies the byte offset from where content 367 will be read. 368 369 - `origin` `(string: "start|end")` - Applies the relative offset to either the 370 start or end of the file. 371 372 ### Sample Request 373 374 ```text 375 $ curl \ 376 https://localhost:4646/v1/client/fs/stream/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/logs/redis.log 377 ``` 378 379 ### Sample Response 380 381 ```json 382 { 383 "File": "alloc/logs/redis.log", 384 "Offset": 3604480, 385 "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." 386 }, 387 { 388 "File": "alloc/logs/redis.log", 389 "FileEvent": "file deleted" 390 } 391 ``` 392 393 #### Field Reference 394 395 The return value is a stream of frames. These frames contain the following 396 fields: 397 398 - `Data` - A base64 encoding of the bytes being streamed. 399 400 - `FileEvent` - An event that could cause a change in the streams position. The 401 possible values are "file deleted" and "file truncated". 402 403 - `Offset` - Offset is the offset into the stream. 404 405 - `File` - The name of the file being streamed. 406 407 ## Stream Logs 408 409 This endpoint streams a task's stderr/stdout logs. 410 411 | Method | Path | Produces | 412 | ------ | ---------------------------- | -------------------------- | 413 | `GET` | `/client/fs/logs/:alloc_id` | `text/plain` | 414 415 The table below shows this endpoint's support for 416 [blocking queries](/api/index.html#blocking-queries) and 417 [required ACLs](/api/index.html#acls). 418 419 | Blocking Queries | ACL Required | 420 | ---------------- | -------------------------------------------- | 421 | `NO` | `namespace:read-logs` or `namespace:read-fs` | 422 423 ### Parameters 424 425 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 426 This is specified as part of the URL. Note, this must be the _full_ allocation 427 ID, not the short 8-character one. This is specified as part of the path. 428 429 - `task` `(string: <required>)` - Specifies the name of the task inside the 430 allocation to stream logs from. 431 432 - `follow` `(bool: false)`- Specifies whether to tail the logs. 433 434 - `type` `(string: "stderr|stdout")` - Specifies the stream to stream. 435 436 - `offset` `(int: 0)` - Specifies the offset to start streaming from. 437 438 - `origin` `(string: "start|end")` - Specifies either "start" or "end" and 439 applies the offset relative to either the start or end of the logs 440 respectively. Defaults to "start". 441 442 - `plain` `(bool: false)` - Return just the plain text without framing. This can 443 be useful when viewing logs in a browser. 444 445 ### Sample Request 446 447 ```text 448 $ curl \ 449 https://localhost:4646/v1/client/fs/logs/5fc98185-17ff-26bc-a802-0c74fa471c99 450 ``` 451 452 ### Sample Response 453 454 ```json 455 { 456 "File": "alloc/logs/redis.stdout.0", 457 "Offset": 3604480, 458 "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." 459 }, 460 { 461 "File": "alloc/logs/redis.stdout.0", 462 "FileEvent": "file deleted" 463 } 464 ``` 465 466 #### Field Reference 467 468 The return value is a stream of frames. These frames contain the following 469 fields: 470 471 - `Data` - A base64 encoding of the bytes being streamed. 472 473 - `FileEvent` - An event that could cause a change in the streams position. The 474 possible values are "file deleted" and "file truncated". 475 476 - `Offset` - Offset is the offset into the stream. 477 478 - `File` - The name of the file being streamed. 479 480 ## List Files 481 482 This endpoint lists files in an allocation directory. 483 484 | Method | Path | Produces | 485 | ------ | ---------------------------- | -------------------------- | 486 | `GET` | `/client/fs/ls/:alloc_id` | `text/plain` | 487 488 The table below shows this endpoint's support for 489 [blocking queries](/api/index.html#blocking-queries) and 490 [required ACLs](/api/index.html#acls). 491 492 | Blocking Queries | ACL Required | 493 | ---------------- | ------------------- | 494 | `NO` | `namespace:read-fs` | 495 496 ### Parameters 497 498 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 499 This is specified as part of the URL. Note, this must be the _full_ allocation 500 ID, not the short 8-character one. This is specified as part of the path. 501 502 - `path` `(string: "/")` - Specifies the path of the file to read, relative to 503 the root of the allocation directory. 504 505 ### Sample Request 506 507 ```text 508 $ curl \ 509 https://localhost:4646/v1/client/fs/ls/5fc98185-17ff-26bc-a802-0c74fa471c99 510 ``` 511 512 ### Sample Response 513 514 ```json 515 [ 516 { 517 "Name": "alloc", 518 "IsDir": true, 519 "Size": 4096, 520 "FileMode": "drwxrwxr-x", 521 "ModTime": "2016-03-15T15:40:00.414236712-07:00" 522 }, 523 { 524 "Name": "redis", 525 "IsDir": true, 526 "Size": 4096, 527 "FileMode": "drwxrwxr-x", 528 "ModTime": "2016-03-15T15:40:56.810238153-07:00" 529 } 530 ] 531 ``` 532 533 ## Stat File 534 535 This endpoint stats a file in an allocation. 536 537 | Method | Path | Produces | 538 | ------ | ---------------------------- | -------------------------- | 539 | `GET` | `/client/fs/stat/:alloc_id` | `text/plain` | 540 541 The table below shows this endpoint's support for 542 [blocking queries](/api/index.html#blocking-queries) and 543 [required ACLs](/api/index.html#acls). 544 545 | Blocking Queries | ACL Required | 546 | ---------------- | ------------------- | 547 | `NO` | `namespace:read-fs` | 548 549 ### Parameters 550 551 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 552 This is specified as part of the URL. Note, this must be the _full_ allocation 553 ID, not the short 8-character one. This is specified as part of the path. 554 555 - `path` `(string: "/")` - Specifies the path of the file to read, relative to 556 the root of the allocation directory. 557 558 ### Sample Request 559 560 ```text 561 $ curl \ 562 https://localhost:4646/v1/client/fs/stat/5fc98185-17ff-26bc-a802-0c74fa471c99 563 ``` 564 565 ### Sample Response 566 567 ```json 568 { 569 "Name": "redis-syslog-collector.out", 570 "IsDir": false, 571 "Size": 96, 572 "FileMode": "-rw-rw-r--", 573 "ModTime": "2016-03-15T15:40:56.822238153-07:00" 574 } 575 ``` 576 577 ## GC Allocation 578 579 This endpoint forces a garbage collection of a particular, stopped allocation 580 on a node. 581 582 | Method | Path | Produces | 583 | ------ | --------------------------------- | -------------------------- | 584 | `GET` | `/client/allocation/:alloc_id/gc` | `application/json` | 585 586 The table below shows this endpoint's support for 587 [blocking queries](/api/index.html#blocking-queries) and 588 [required ACLs](/api/index.html#acls). 589 590 | Blocking Queries | ACL Required | 591 | ---------------- | ---------------------- | 592 | `NO` | `namespace:submit-job` | 593 594 ### Parameters 595 596 - `:alloc_id` `(string: <required>)` - Specifies the allocation ID to query. 597 This is specified as part of the URL. Note, this must be the _full_ allocation 598 ID, not the short 8-character one. This is specified as part of the path. 599 600 ### Sample Request 601 602 ```text 603 $ curl \ 604 https://nomad.rocks/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/gc 605 ``` 606 607 ## GC All Allocation 608 609 This endpoint forces a garbage collection of all stopped allocations on a node. 610 611 | Method | Path | Produces | 612 | ------ | ---------------------------- | -------------------------- | 613 | `GET` | `/client/gc` | `text/plain` | 614 615 The table below shows this endpoint's support for 616 [blocking queries](/api/index.html#blocking-queries) and 617 [required ACLs](/api/index.html#acls). 618 619 | Blocking Queries | ACL Required | 620 | ---------------- | ------------ | 621 | `NO` | `node:write` | 622 623 ### Parameters 624 625 - `node_id` `(string: <optional>)` - Specifies the node to target. This is 626 required when the endpoint is being accessed via a server. This is specified as 627 part of the URL. Note, this must be the _full_ node ID, not the short 628 8-character one. This is specified as part of the path. 629 630 ### Sample Request 631 632 ```text 633 $ curl \ 634 https://localhost:4646/v1/client/gc 635 ```