mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
53b083b8c5
* Move commands from docs to its own root-level directory * temporarily use modified dev-portal branch with nomad ia changes * explicitly clone nomad ia exp branch * retrigger build, fixed dev-portal broken build * architecture, concepts and get started individual pages * fix get started section destinations * reference section * update repo comment in website-build.sh to show branch * docs nav file update capitalization * update capitalization to force deploy * remove nomad-vs-kubernetes dir; move content to what is nomad pg * job section * Nomad operations category, deploy section * operations category, govern section * operations - manage * operations/scale; concepts scheduling fix * networking * monitor * secure section * remote auth-methods folder and move up pages to sso; linkcheck * Fix install2deploy redirects * fix architecture redirects * Job section: Add missing section index pages * Add section index pages so breadcrumbs build correctly * concepts/index fix front matter indentation * move task driver plugin config to new deploy section * Finish adding full URL to tutorials links in nav * change SSO to Authentication in nav and file system * Docs NomadIA: Move tutorials into NomadIA branch (#26132) * Move governance and policy from tutorials to docs * Move tutorials content to job-declare section * run jobs section * stateful workloads * advanced job scheduling * deploy section * manage section * monitor section * secure/acl and secure/authorization * fix example that contains an unseal key in real format * remove images from sso-vault * secure/traffic * secure/workload-identities * vault-acl change unseal key and root token in command output sample * remove lines from sample output * fix front matter * move nomad pack tutorials to tools * search/replace /nomad/tutorials links * update acl overview with content from deleted architecture/acl * fix spelling mistake * linkcheck - fix broken links * fix link to Nomad variables tutorial * fix link to Prometheus tutorial * move who uses Nomad to use cases page; move spec/config shortcuts add dividers * Move Consul out of Integrations; move namespaces to govern * move integrations/vault to secure/vault; delete integrations * move ref arch to docs; rename Deploy Nomad back to Install Nomad * address feedback * linkcheck fixes * Fixed raw_exec redirect * add info from /nomad/tutorials/manage-jobs/jobs * update page content with newer tutorial * link updates for architecture sub-folders * Add redirects for removed section index pages. Fix links. * fix broken links from linkcheck * Revert to use dev-portal main branch instead of nomadIA branch * build workaround: add intro-nav-data.json with single entry * fix content-check error * add intro directory to get around Vercel build error * workound for emtpry directory * remove mdx from /intro/ to fix content-check and git snafu * Add intro index.mdx so Vercel build should work --------- Co-authored-by: Tu Nguyen <im2nguyen@gmail.com>
448 lines
13 KiB
Plaintext
448 lines
13 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](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/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](/nomad/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](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/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,
|
|
"NodesInPool": 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](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/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](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/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](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/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](/nomad/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]: /nomad/api-docs/operator/scheduler#update-scheduler-configuration
|
|
[metrics reference]: /nomad/docs/reference/metrics
|