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