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.