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