github.com/smintz/nomad@v0.8.3/website/source/api/allocations.html.md (about) 1 --- 2 layout: api 3 page_title: Allocations - HTTP API 4 sidebar_current: api-allocations 5 description: |- 6 The /allocation endpoints are used to query for and interact with allocations. 7 --- 8 9 # Allocations HTTP API 10 11 The `/allocation` endpoints are used to query for and interact with allocations. 12 13 ## List Allocations 14 15 This endpoint lists all allocations. 16 17 | Method | Path | Produces | 18 | ------ | ------------------------- | -------------------------- | 19 | `GET` | `/v1/allocations` | `application/json` | 20 21 The table below shows this endpoint's support for 22 [blocking queries](/api/index.html#blocking-queries) and 23 [required ACLs](/api/index.html#acls). 24 25 | Blocking Queries | ACL Required | 26 | ---------------- | -------------------- | 27 | `YES` | `namespace:read-job` | 28 29 ### Parameters 30 31 - `prefix` `(string: "")`- Specifies a string to filter allocations on based on 32 an index prefix. This is specified as a querystring parameter. 33 34 ### Sample Request 35 36 ```text 37 $ curl \ 38 https://localhost:4646/v1/allocations 39 ``` 40 41 ```text 42 $ curl \ 43 https://localhost:4646/v1/allocations?prefix=a8198d79 44 ``` 45 46 ### Sample Response 47 48 ```json 49 [ 50 { 51 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 52 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 53 "Name": "example.cache[0]", 54 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 55 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 56 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 57 "RescheduleTracker": { 58 "Events": [ 59 { 60 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 61 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 62 "RescheduleTime": 1517434161192946200, 63 "Delay":"5000000000" 64 }, 65 ] 66 }, 67 "JobID": "example", 68 "TaskGroup": "cache", 69 "DesiredStatus": "run", 70 "DesiredDescription": "", 71 "ClientStatus": "running", 72 "ClientDescription": "", 73 "TaskStates": { 74 "redis": { 75 "State": "running", 76 "FinishedAt": "0001-01-01T00:00:00Z", 77 "LastRestart": "0001-01-01T00:00:00Z", 78 "Restarts": 0, 79 "StartedAt": "2017-07-25T23:36:26.106431265Z", 80 "Failed": false, 81 "Events": [ 82 { 83 "Type": "Received", 84 "Time": 1495747371795703800, 85 "FailsTask": false, 86 "RestartReason": "", 87 "SetupError": "", 88 "DriverError": "", 89 "ExitCode": 0, 90 "Signal": 0, 91 "Message": "", 92 "KillTimeout": 0, 93 "KillError": "", 94 "KillReason": "", 95 "StartDelay": 0, 96 "DownloadError": "", 97 "ValidationError": "", 98 "DiskLimit": 0, 99 "FailedSibling": "", 100 "VaultError": "", 101 "TaskSignalReason": "", 102 "TaskSignal": "", 103 "DriverMessage": "" 104 }, 105 { 106 "Type": "Driver", 107 "Time": 1495747371798867200, 108 "FailsTask": false, 109 "RestartReason": "", 110 "SetupError": "", 111 "DriverError": "", 112 "ExitCode": 0, 113 "Signal": 0, 114 "Message": "", 115 "KillTimeout": 0, 116 "KillError": "", 117 "KillReason": "", 118 "StartDelay": 0, 119 "DownloadError": "", 120 "ValidationError": "", 121 "DiskLimit": 0, 122 "FailedSibling": "", 123 "VaultError": "", 124 "TaskSignalReason": "", 125 "TaskSignal": "", 126 "DriverMessage": "Downloading image redis:3.2" 127 }, 128 { 129 "Type": "Started", 130 "Time": 1495747379525667800, 131 "FailsTask": false, 132 "RestartReason": "", 133 "SetupError": "", 134 "DriverError": "", 135 "ExitCode": 0, 136 "Signal": 0, 137 "Message": "", 138 "KillTimeout": 0, 139 "KillError": "", 140 "KillReason": "", 141 "StartDelay": 0, 142 "DownloadError": "", 143 "ValidationError": "", 144 "DiskLimit": 0, 145 "FailedSibling": "", 146 "VaultError": "", 147 "TaskSignalReason": "", 148 "TaskSignal": "", 149 "DriverMessage": "" 150 } 151 ] 152 } 153 }, 154 "CreateIndex": 54, 155 "ModifyIndex": 57, 156 "CreateTime": 1495747371794276400, 157 "ModifyTime": 1495747371794276400 158 } 159 ] 160 ``` 161 162 ## Read Allocation 163 164 This endpoint reads information about a specific allocation. 165 166 | Method | Path | Produces | 167 | ------ | -------------------------- | -------------------------- | 168 | `GET` | `/v1/allocation/:alloc_id` | `application/json` | 169 170 The table below shows this endpoint's support for 171 [blocking queries](/api/index.html#blocking-queries) and 172 [required ACLs](/api/index.html#acls). 173 174 | Blocking Queries | ACL Required | 175 | ---------------- | -------------------- | 176 | `YES` | `namespace:read-job` | 177 178 ### Parameters 179 180 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 181 must be the full UUID, not the short 8-character one. This is specified as 182 part of the path. 183 184 ### Sample Request 185 186 ```text 187 $ curl \ 188 https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577 189 ``` 190 191 ### Sample Response 192 193 ```json 194 { 195 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 196 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 197 "Name": "example.cache[0]", 198 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 199 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 200 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 201 "RescheduleTracker": { 202 "Events": [ 203 { 204 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 205 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 206 "RescheduleTime": 1517434161192946200, 207 "Delay":"5000000000" 208 }, 209 ] 210 }, 211 "JobID": "example", 212 "Job": { 213 "Region": "global", 214 "ID": "example", 215 "ParentID": "", 216 "Name": "example", 217 "Type": "service", 218 "Priority": 50, 219 "AllAtOnce": false, 220 "Datacenters": [ 221 "dc1" 222 ], 223 "Constraints": null, 224 "TaskGroups": [ 225 { 226 "Name": "cache", 227 "Count": 1, 228 "Constraints": null, 229 "RestartPolicy": { 230 "Attempts": 10, 231 "Interval": 300000000000, 232 "Delay": 25000000000, 233 "Mode": "delay" 234 }, 235 "Tasks": [ 236 { 237 "Name": "redis", 238 "Driver": "docker", 239 "User": "", 240 "Config": { 241 "port_map": [ 242 { 243 "db": 6379 244 } 245 ], 246 "image": "redis:3.2" 247 }, 248 "Env": null, 249 "Services": [ 250 { 251 "Name": "redis-cache", 252 "PortLabel": "db", 253 "Tags": [ 254 "global", 255 "cache" 256 ], 257 "Checks": [ 258 { 259 "Name": "alive", 260 "Type": "tcp", 261 "Command": "", 262 "Args": null, 263 "Path": "", 264 "Protocol": "", 265 "PortLabel": "", 266 "Interval": 10000000000, 267 "Timeout": 2000000000, 268 "InitialStatus": "" 269 } 270 ] 271 } 272 ], 273 "Vault": null, 274 "Templates": null, 275 "Constraints": null, 276 "Resources": { 277 "CPU": 500, 278 "MemoryMB": 10, 279 "DiskMB": 0, 280 "IOPS": 0, 281 "Networks": [ 282 { 283 "Device": "", 284 "CIDR": "", 285 "IP": "", 286 "MBits": 10, 287 "ReservedPorts": null, 288 "DynamicPorts": [ 289 { 290 "Label": "db", 291 "Value": 0 292 } 293 ] 294 } 295 ] 296 }, 297 "DispatchPayload": null, 298 "Meta": null, 299 "KillTimeout": 5000000000, 300 "LogConfig": { 301 "MaxFiles": 10, 302 "MaxFileSizeMB": 10 303 }, 304 "Artifacts": null, 305 "Leader": false 306 } 307 ], 308 "EphemeralDisk": { 309 "Sticky": false, 310 "SizeMB": 300, 311 "Migrate": false 312 }, 313 "Meta": null 314 } 315 ], 316 "Update": { 317 "Stagger": 10000000000, 318 "MaxParallel": 0 319 }, 320 "Periodic": null, 321 "ParameterizedJob": null, 322 "Payload": null, 323 "Meta": null, 324 "VaultToken": "", 325 "Status": "pending", 326 "StatusDescription": "", 327 "CreateIndex": 52, 328 "ModifyIndex": 52, 329 "JobModifyIndex": 52 330 }, 331 "TaskGroup": "cache", 332 "Resources": { 333 "CPU": 500, 334 "MemoryMB": 10, 335 "DiskMB": 300, 336 "IOPS": 0, 337 "Networks": [ 338 { 339 "Device": "lo0", 340 "CIDR": "", 341 "IP": "127.0.0.1", 342 "MBits": 10, 343 "ReservedPorts": null, 344 "DynamicPorts": [ 345 { 346 "Label": "db", 347 "Value": 23116 348 } 349 ] 350 } 351 ] 352 }, 353 "SharedResources": { 354 "CPU": 0, 355 "MemoryMB": 0, 356 "DiskMB": 300, 357 "IOPS": 0, 358 "Networks": null 359 }, 360 "TaskResources": { 361 "redis": { 362 "CPU": 500, 363 "MemoryMB": 10, 364 "DiskMB": 0, 365 "IOPS": 0, 366 "Networks": [ 367 { 368 "Device": "lo0", 369 "CIDR": "", 370 "IP": "127.0.0.1", 371 "MBits": 10, 372 "ReservedPorts": null, 373 "DynamicPorts": [ 374 { 375 "Label": "db", 376 "Value": 23116 377 } 378 ] 379 } 380 ] 381 } 382 }, 383 "Metrics": { 384 "NodesEvaluated": 1, 385 "NodesFiltered": 0, 386 "NodesAvailable": { 387 "dc1": 1 388 }, 389 "ClassFiltered": null, 390 "ConstraintFiltered": null, 391 "NodesExhausted": 0, 392 "ClassExhausted": null, 393 "DimensionExhausted": null, 394 "Scores": { 395 "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244 396 }, 397 "AllocationTime": 31729, 398 "CoalescedFailures": 0 399 }, 400 "DesiredStatus": "run", 401 "DesiredDescription": "", 402 "ClientStatus": "running", 403 "ClientDescription": "", 404 "TaskStates": { 405 "redis": { 406 "State": "running", 407 "Failed": false, 408 "FinishedAt": "0001-01-01T00:00:00Z", 409 "LastRestart": "0001-01-01T00:00:00Z", 410 "Restarts": 0, 411 "StartedAt": "2017-07-25T23:36:26.106431265Z", 412 "Events": [ 413 { 414 "Type": "Received", 415 "Time": 1495747371795703800, 416 "FailsTask": false, 417 "RestartReason": "", 418 "SetupError": "", 419 "DriverError": "", 420 "ExitCode": 0, 421 "Signal": 0, 422 "Message": "", 423 "KillTimeout": 0, 424 "KillError": "", 425 "KillReason": "", 426 "StartDelay": 0, 427 "DownloadError": "", 428 "ValidationError": "", 429 "DiskLimit": 0, 430 "FailedSibling": "", 431 "VaultError": "", 432 "TaskSignalReason": "", 433 "TaskSignal": "", 434 "DriverMessage": "" 435 }, 436 { 437 "Type": "Driver", 438 "Time": 1495747371798867200, 439 "FailsTask": false, 440 "RestartReason": "", 441 "SetupError": "", 442 "DriverError": "", 443 "ExitCode": 0, 444 "Signal": 0, 445 "Message": "", 446 "KillTimeout": 0, 447 "KillError": "", 448 "KillReason": "", 449 "StartDelay": 0, 450 "DownloadError": "", 451 "ValidationError": "", 452 "DiskLimit": 0, 453 "FailedSibling": "", 454 "VaultError": "", 455 "TaskSignalReason": "", 456 "TaskSignal": "", 457 "DriverMessage": "Downloading image redis:3.2" 458 }, 459 { 460 "Type": "Started", 461 "Time": 1495747379525667800, 462 "FailsTask": false, 463 "RestartReason": "", 464 "SetupError": "", 465 "DriverError": "", 466 "ExitCode": 0, 467 "Signal": 0, 468 "Message": "", 469 "KillTimeout": 0, 470 "KillError": "", 471 "KillReason": "", 472 "StartDelay": 0, 473 "DownloadError": "", 474 "ValidationError": "", 475 "DiskLimit": 0, 476 "FailedSibling": "", 477 "VaultError": "", 478 "TaskSignalReason": "", 479 "TaskSignal": "", 480 "DriverMessage": "" 481 } 482 ] 483 } 484 }, 485 "PreviousAllocation": "", 486 "CreateIndex": 54, 487 "ModifyIndex": 57, 488 "AllocModifyIndex": 54, 489 "CreateTime": 1495747371794276400, 490 "ModifyTime": 1495747371794276400 491 } 492 ``` 493 494 #### Field Reference 495 496 - `TaskStates` - A map of tasks to their current state and the latest events 497 that have effected the state. `TaskState` objects contain the following 498 fields: 499 500 - `State`: The task's current state. It can have one of the following 501 values: 502 503 - `TaskStatePending` - The task is waiting to be run, either for the first 504 time or due to a restart. 505 506 - `TaskStateRunning` - The task is currently running. 507 508 - `TaskStateDead` - The task is dead and will not run again. 509 510 - `StartedAt`: The time the task was last started at. Can be updated through 511 restarts. 512 513 - `FinishedAt`: The time the task was finished at. 514 515 - `LastRestart`: The last time the task was restarted. 516 517 - `Restarts`: The number of times the task has restarted. 518 519 - `Events` - An event contains metadata about the event. The latest 10 events 520 are stored per task. Each event is timestamped (Unix nanoseconds) and has one 521 of the following types: 522 523 - `Setup Failure` - The task could not be started because there was a 524 failure setting up the task prior to it running. 525 526 - `Driver Failure` - The task could not be started due to a failure in the 527 driver. 528 529 - `Started` - The task was started; either for the first time or due to a 530 restart. 531 532 - `Terminated` - The task was started and exited. 533 534 - `Killing` - The task has been sent the kill signal. 535 536 - `Killed` - The task was killed by a user. 537 538 - `Received` - The task has been pulled by the client at the given timestamp. 539 540 - `Failed Validation` - The task was invalid and as such it didn't run. 541 542 - `Restarting` - The task terminated and is being restarted. 543 544 - `Not Restarting` - the task has failed and is not being restarted because 545 it has exceeded its restart policy. 546 547 - `Downloading Artifacts` - The task is downloading the artifact(s) 548 - specified in the task. 549 550 - `Failed Artifact Download` - Artifact(s) specified in the task failed to 551 download. 552 553 - `Restart Signaled` - The task was singled to be restarted. 554 555 - `Signaling` - The task was is being sent a signal. 556 557 - `Sibling Task Failed` - A task in the same task group failed. 558 559 - `Leader Task Dead` - The group's leader task is dead. 560 561 - `Driver` - A message from the driver. 562 563 - `Task Setup` - Task setup messages. 564 565 - `Building Task Directory` - Task is building its file system. 566 567 Depending on the type the event will have applicable annotations.