mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 02:15:43 +03:00
972708aaed
API queries can request pagination using the `NextToken` and `PerPage` fields of `QueryOptions`, when supported by the underlying API. Add a `NextToken` field to the `structs.QueryMeta` so that we have a common field across RPCs to tell the caller where to resume paging from on their next API call. Include this field on the `api.QueryMeta` as well so that it's available for future versions of List HTTP APIs that wrap the response with `QueryMeta` rather than returning a simple list of structs. In the meantime callers can get the `X-Nomad-NextToken`. Add pagination to the `Eval.List` RPC by checking for pagination token and page size in `QueryOptions`. This will allow resuming from the last ID seen so long as the query parameters and the state store itself are unchanged between requests. Add filtering by job ID or evaluation status over the results we get out of the state store. Parse the query parameters of the `Eval.List` API into the arguments expected for filtering in the RPC call.
285 lines
7.5 KiB
Plaintext
285 lines
7.5 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Evaluations - HTTP API
|
|
description: The /evaluation are used to query for and interact with evaluations.
|
|
---
|
|
|
|
# Evaluations HTTP API
|
|
|
|
The `/evaluation` endpoints are used to query for and interact with evaluations.
|
|
|
|
## List Evaluations
|
|
|
|
This endpoint lists all evaluations.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------- | ------------------ |
|
|
| `GET` | `/v1/evaluations` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------- |
|
|
| `YES` | `namespace:read-job` |
|
|
|
|
### Parameters
|
|
|
|
- `prefix` `(string: "")`- Specifies a string to filter evaluations based on an
|
|
ID prefix. Because the value is decoded to bytes, the prefix must have an
|
|
even number of hexadecimal characters (0-9a-f). This is specified as a query
|
|
string parameter.
|
|
|
|
- `next_token` `(string: "")` - This endpoint supports paging. The
|
|
`next_token` parameter accepts a string which is the `ID` field of
|
|
the next expected evaluation. This value can be obtained from the
|
|
`X-Nomad-NextToken` header from the previous response.
|
|
|
|
- `per_page` `(int: 0)` - Specifies a maximum number of evaluations to
|
|
return for this request. If omitted, the response is not
|
|
paginated. The `ID` of the last evaluation in the response can be
|
|
used as the `last_token` of the next request to fetch additional
|
|
pages.
|
|
|
|
- `job` `(string: "")` - Filter the list of evaluations to a specific
|
|
job ID.
|
|
|
|
- `status` `(string: "")` - Filter the list of evaluations to a
|
|
specific evaluation status (one of `blocked`, `pending`, `complete`,
|
|
`failed`, or `canceled`).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/evaluations
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/evaluations?prefix=25ba81
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
|
|
"Priority": 50,
|
|
"Type": "service",
|
|
"TriggeredBy": "job-register",
|
|
"JobID": "example",
|
|
"JobModifyIndex": 52,
|
|
"NodeID": "",
|
|
"NodeModifyIndex": 0,
|
|
"Status": "complete",
|
|
"StatusDescription": "",
|
|
"Wait": 0,
|
|
"NextEval": "",
|
|
"PreviousEval": "",
|
|
"BlockedEval": "",
|
|
"FailedTGAllocs": null,
|
|
"ClassEligibility": null,
|
|
"EscapedComputedClass": false,
|
|
"AnnotatePlan": false,
|
|
"SnapshotIndex": 53,
|
|
"QueuedAllocations": {
|
|
"cache": 0
|
|
},
|
|
"CreateIndex": 53,
|
|
"ModifyIndex": 55
|
|
}
|
|
]
|
|
```
|
|
|
|
## Read Evaluation
|
|
|
|
This endpoint reads information about a specific evaluation by ID.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------- | ------------------ |
|
|
| `GET` | `/v1/evaluation/:eval_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------- |
|
|
| `YES` | `namespace:read-job` |
|
|
|
|
### Parameters
|
|
|
|
- `:eval_id` `(string: <required>)`- Specifies the UUID of the evaluation. This
|
|
must be the full UUID, not the short 8-character one. This is specified as
|
|
part of the path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/evaluation/5456bd7a-9fc0-c0dd-6131-cbee77f57577
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"ID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
|
|
"Priority": 50,
|
|
"Type": "service",
|
|
"TriggeredBy": "job-register",
|
|
"JobID": "example",
|
|
"JobModifyIndex": 52,
|
|
"NodeID": "",
|
|
"NodeModifyIndex": 0,
|
|
"Status": "complete",
|
|
"StatusDescription": "",
|
|
"Wait": 0,
|
|
"NextEval": "",
|
|
"PreviousEval": "",
|
|
"BlockedEval": "",
|
|
"FailedTGAllocs": null,
|
|
"ClassEligibility": null,
|
|
"EscapedComputedClass": false,
|
|
"AnnotatePlan": false,
|
|
"SnapshotIndex": 53,
|
|
"QueuedAllocations": {
|
|
"cache": 0
|
|
},
|
|
"CreateIndex": 53,
|
|
"ModifyIndex": 55
|
|
}
|
|
```
|
|
|
|
## List Allocations for Evaluation
|
|
|
|
This endpoint lists the allocations created or modified for the given
|
|
evaluation.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------------- | ------------------ |
|
|
| `GET` | `/v1/evaluation/:eval_id/allocations` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------- |
|
|
| `YES` | `namespace:read-job` |
|
|
|
|
### Parameters
|
|
|
|
- `:eval_id` `(string: <required>)`- Specifies the UUID of the evaluation. This
|
|
must be the full UUID, not the short 8-character one. This is specified as
|
|
part of the path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/evaluation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/allocations
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
|
|
"EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
|
|
"Name": "example.cache[0]",
|
|
"NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
|
|
"JobID": "example",
|
|
"TaskGroup": "cache",
|
|
"DesiredStatus": "run",
|
|
"DesiredDescription": "",
|
|
"ClientStatus": "running",
|
|
"ClientDescription": "",
|
|
"TaskStates": {
|
|
"redis": {
|
|
"State": "running",
|
|
"Failed": false,
|
|
"Events": [
|
|
{
|
|
"Type": "Received",
|
|
"Time": 1495747371795703800,
|
|
"FailsTask": false,
|
|
"RestartReason": "",
|
|
"SetupError": "",
|
|
"DriverError": "",
|
|
"ExitCode": 0,
|
|
"Signal": 0,
|
|
"Message": "",
|
|
"KillTimeout": 0,
|
|
"KillError": "",
|
|
"KillReason": "",
|
|
"StartDelay": 0,
|
|
"DownloadError": "",
|
|
"ValidationError": "",
|
|
"DiskLimit": 0,
|
|
"FailedSibling": "",
|
|
"VaultError": "",
|
|
"TaskSignalReason": "",
|
|
"TaskSignal": "",
|
|
"DriverMessage": ""
|
|
},
|
|
{
|
|
"Type": "Driver",
|
|
"Time": 1495747371798867200,
|
|
"FailsTask": false,
|
|
"RestartReason": "",
|
|
"SetupError": "",
|
|
"DriverError": "",
|
|
"ExitCode": 0,
|
|
"Signal": 0,
|
|
"Message": "",
|
|
"KillTimeout": 0,
|
|
"KillError": "",
|
|
"KillReason": "",
|
|
"StartDelay": 0,
|
|
"DownloadError": "",
|
|
"ValidationError": "",
|
|
"DiskLimit": 0,
|
|
"FailedSibling": "",
|
|
"VaultError": "",
|
|
"TaskSignalReason": "",
|
|
"TaskSignal": "",
|
|
"DriverMessage": "Downloading image redis:3.2"
|
|
},
|
|
{
|
|
"Type": "Started",
|
|
"Time": 1495747379525667800,
|
|
"FailsTask": false,
|
|
"RestartReason": "",
|
|
"SetupError": "",
|
|
"DriverError": "",
|
|
"ExitCode": 0,
|
|
"Signal": 0,
|
|
"Message": "",
|
|
"KillTimeout": 0,
|
|
"KillError": "",
|
|
"KillReason": "",
|
|
"StartDelay": 0,
|
|
"DownloadError": "",
|
|
"ValidationError": "",
|
|
"DiskLimit": 0,
|
|
"FailedSibling": "",
|
|
"VaultError": "",
|
|
"TaskSignalReason": "",
|
|
"TaskSignal": "",
|
|
"DriverMessage": ""
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"CreateIndex": 54,
|
|
"ModifyIndex": 57,
|
|
"CreateTime": 1495747371794276400
|
|
}
|
|
]
|
|
```
|