298 lines
8.2 KiB
Plaintext
298 lines
8.2 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 and and is used before any `filter` expression is applied.
|
|
|
|
- `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.
|
|
|
|
- `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering)
|
|
used to filter the results. Consider using pagination or a query parameter to
|
|
reduce resource used to serve the request.
|
|
|
|
- `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`).
|
|
|
|
- `namespace` `(string: "default")` - Specifies the target namespace.
|
|
Specifying `*` will return all evaluations across all authorized namespaces.
|
|
This parameter is used before any `filter` expression is applied.
|
|
|
|
- `reverse` `(bool: false)` - Specifies the list of returned evaluations should
|
|
be sorted in the reverse order. By default evaluations are returned sorted in
|
|
chronological order (older evaluations first), or in lexicographical order by
|
|
their ID if the `prefix` query parameter is used.
|
|
|
|
### 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
|
|
}
|
|
]
|
|
```
|