65f7abf2f4
Closes #12927 Closes #12958 This PR updates the version of redis used in our examples from 3.2 to 7. The old version is very not supported anymore, and we should be setting a good example by using a supported version. The long-form example job is now fixed so that the service stanza uses nomad as the service discovery provider, and so now the job runs without a requirement of having Consul running and configured.
335 lines
9.5 KiB
Plaintext
335 lines
9.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 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.
|
|
|
|
- `related` `(bool: false)` - Specifies if related evaluations should be
|
|
returned. Related evaluations are the ones that can be reached by following
|
|
the trail of IDs for `NextEval`, `PreviousEval`, and `BlockedEval`. This is
|
|
specified as a query parameter.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/evaluation/2deb5f06-a100-f01a-3316-5e501a4965e7?related=true
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"CreateIndex": 28,
|
|
"CreateTime": 1647394818583344000,
|
|
"FailedTGAllocs": {
|
|
"cache": {
|
|
"AllocationTime": 4111,
|
|
"ClassExhausted": null,
|
|
"ClassFiltered": null,
|
|
"CoalescedFailures": 0,
|
|
"ConstraintFiltered": null,
|
|
"DimensionExhausted": null,
|
|
"NodesAvailable": {
|
|
"dc1": 0
|
|
},
|
|
"NodesEvaluated": 0,
|
|
"NodesExhausted": 0,
|
|
"NodesFiltered": 0,
|
|
"QuotaExhausted": null,
|
|
"ResourcesExhausted": null,
|
|
"ScoreMetaData": null,
|
|
"Scores": null
|
|
}
|
|
},
|
|
"ID": "2deb5f06-a100-f01a-3316-5e501a4965e7",
|
|
"JobID": "example",
|
|
"ModifyIndex": 28,
|
|
"ModifyTime": 1647394818583344000,
|
|
"Namespace": "default",
|
|
"PreviousEval": "0f98f7ea-59ae-4d90-d9bd-b8ce80b9e100",
|
|
"Priority": 50,
|
|
"RelatedEvals": [
|
|
{
|
|
"BlockedEval": "2deb5f06-a100-f01a-3316-5e501a4965e7",
|
|
"CreateIndex": 27,
|
|
"CreateTime": 1647394818582736000,
|
|
"DeploymentID": "79ae0a49-acf6-0fcf-183f-8646f3167b88",
|
|
"ID": "0f98f7ea-59ae-4d90-d9bd-b8ce80b9e100",
|
|
"JobID": "example",
|
|
"ModifyIndex": 30,
|
|
"ModifyTime": 1647394818583565000,
|
|
"Namespace": "default",
|
|
"NextEval": "",
|
|
"NodeID": "",
|
|
"PreviousEval": "",
|
|
"Priority": 50,
|
|
"Status": "complete",
|
|
"StatusDescription": "",
|
|
"TriggeredBy": "node-drain",
|
|
"Type": "service",
|
|
"WaitUntil": null
|
|
}
|
|
],
|
|
"SnapshotIndex": 27,
|
|
"Status": "blocked",
|
|
"StatusDescription": "created to place remaining allocations",
|
|
"TriggeredBy": "queued-allocs",
|
|
"Type": "service"
|
|
}
|
|
```
|
|
|
|
## 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:7"
|
|
},
|
|
{
|
|
"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
|
|
}
|
|
]
|
|
```
|