luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-nomad/website/content/api-docs/evaluations.mdx
Tim Gross 9e1c0b46d8
API for Eval.Count (#15147) 
Add a new `Eval.Count` RPC and associated HTTP API endpoints. This API is
designed to support interactive use in the `nomad eval delete` command to get a
count of evals expected to be deleted before doing so.

The state store operations to do this sort of thing are somewhat expensive, but
it's cheaper than serializing a big list of evals to JSON. Note that although it
seems like this could be done as an extra parameter and response field on
`Eval.List`, having it as its own endpoint avoids having to change the response
body shape and lets us avoid handling the legacy filter params supported by
`Eval.List`.
2022-11-07 08:53:19 -05:00

447 lines
13 KiB
Plaintext
Raw Blame History

---
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 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"
}
```
## Delete Evaluations
This endpoint deletes evaluations. In order to utilise this endpoint the
eval broker should be paused via the
[operator scheduler update configuration][update_scheduler_configuration] API
endpoint.
This API endpoint should be used cautiously and only in outage situations where
there is a large backlog of evaluations not being processed. During most normal
and outage scenarios, Nomad's reconciliation and state management will handle
evaluations as needed.
| Method | Path | Produces |
| --------- | ----------------- | ------------------ |
| `DELETE` | `/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 |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `EvalIDs` `(array<string>: <required>)`- An array of evaluation UUIDs to
delete. This must be a full length UUID and not a prefix.
### Sample Payload
```javascript
{
"EvalIDs": [
"167ec27d-2e36-979a-280a-a6b920d382db",
"6c193955-ac66-42e2-f4c7-f1fc707f1f5e"
]
}
```
### Sample Request
```shell-session
$ curl \
--request DELETE \
--data @payload.json \
https://localhost:4646/v1/evaluations
```
## 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
}
]
```
## Count Evaluations
This endpoint counts evaluations. Note that Nomad's state store architecture
makes calculating this count unexpectedly expensive (similar in cost to the List
API), and this API was designed for use during recovery operations with the
`nomad eval delete` command. It is not recommended to use this API for
monitoring. The `nomad.nomad.broker.*` metrics are better for that use
case. See the [metrics reference][] for details.
| Method | Path | Produces |
|--------|-------------------------|--------------------|
| `GET` | `/v1/evaluations/count` | `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 is used before any `filter` expression is applied.
- `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering) used
to filter the results.
- `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.
### Sample Request
```shell-session
$ curl \
https://localhost:4646/v1/evaluations/count
```
```shell-session
$ curl \
https://localhost:4646/v1/evaluations/count?prefix=25ba81
```
### Sample Response
```json
{
"Count": 36
"Index": 133,
"KnownLeader": true,
"LastContact": 0,
"NextToken": ""
}
```
[update_scheduler_configuration]: /api-docs/operator/scheduler#update-scheduler-configuration
[metrics reference]: /docs/operations/metrics-reference
Reference in a new issue View git blame Copy permalink