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