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