luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

docs: add recommendations API documentation.

Browse source
This commit is contained in:
James Rasell 2020-10-27 16:23:38 +01:00
parent 592c28c6ba
commit 2ccf69ac01
No known key found for this signature in database
GPG key ID: AA7D460F5C8377AA
2 changed files with 375 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
website/data/api-navigation.js
View file

@ -26,6 +26,7 @@ export default [
'operator',
'plugins',
'quotas',
'recommendations',
'regions',
'scaling-policies',
'search',

374
website/pages/api-docs/recommendations.mdx Normal file
View file

@ -0,0 +1,374 @@
---
layout: api
page_title: Recommendations - HTTP API
sidebar_title: Recommendations
description: >-
The /recommendation endpoints are used to query for and interact with Dynamic
Application Sizing recommendations.
---
# Recommendation HTTP API
The `/recommendation` endpoints are used to query and interact with Dynamic
Application Sizing recommendations.
~> **Enterprise Only!** This API endpoint and functionality only exists in
Nomad Enterprise. This is not present in the open source version of Nomad.
## List Recommendations
This endpoint lists all the currently available recommendations and provides
optional filtering of that list.
| Method | Path | Produces |
| ------ | --------------------- | ------------------ |
| `GET` | `/v1/recommendations` | `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` or `namespace:submit-recommendation` or `namespace:submit-job` |
### Parameters
- `group` `(string: "")` - Specifies the task group name to filter within a job. If
specified, the `job` parameter must also be specified.
- `job` `(string: "")` - Specifies the job ID to filter the recommendations list by.
- `namespace` `(string: "default")` - Specifies the namespace to search. Specifying
`*` would return all recommendations across all the authorized namespaces.
- `task` `(string: "")` - Specifies the task name to filter within a job and task
group. If specified, the `job` and `group` query parameters must also be
specified.
### Sample Request
```shell-session
$ curl \
https://localhost:4646/v1/recommendations
```
```shell-session
$ curl \
https://localhost:4646/v1/recommendations?namespace=*
```
```shell-session
$ curl \
https://localhost:4646/v1/recommendations?namespace=*&job=example&group=cache&task=redis
```
### Sample Response
```json
[
{
"ID": "cb80a13d-20d8-fb05-db3f-4ea0fe667b1b",
"Region": "global",
"Namespace": "default",
"JobID": "example",
"JobVersion": 0,
"Group": "cache",
"Task": "redis",
"Resource": "MemoryMB",
"Value": 10,
"Current": 200,
"Meta": {
"nomad_autoscaler.count.capped": true,
"nomad_autoscaler.count.original": 6,
"nomad_autoscaler.reason_history": [],
"nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c",
"num_evaluated_windows": 1148,
"window_size": 300000000000
},
"Stats": {
"min": 2.6640625,
"p99": 6.51171875,
"max": 6.515625,
"mean": 4.816847859995009
},
"EnforceVersion": false,
"SubmitTime": 1603372587714807000,
"CreateIndex": 5193,
"ModifyIndex": 10437
},
{
"ID": "fdd2b5f1-e6ad-110e-75b9-8f9410e1d8ab",
"Region": "global",
"Namespace": "default",
"JobID": "example",
"JobVersion": 0,
"Group": "cache",
"Task": "redis",
"Resource": "CPU",
"Value": 57,
"Current": 500,
"Meta": {
"window_size": 300000000000,
"nomad_policy_id": "b2c64295-4315-2fdc-6158-a27156808729",
"num_evaluated_windows": 1117
},
"Stats": {
"min": 0,
"p99": 50,
"max": 63.46186447143555,
"mean": 0.3649455045779875
},
"EnforceVersion": false,
"SubmitTime": 1603372287894356000,
"CreateIndex": 5275,
"ModifyIndex": 10419
}
]
```
## Read Recommendation
This endpoint reads information about a specific recommendation.
| Method | Path | Produces |
| ------ | --------------------------------------- | ------------------ |
| `GET` | `/v1/recommendation/:recommendation_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
- `:recommendation_id` `(string: <required>)`- Specifies the recommendation ID to
query. This is specified as part of the path.
### Sample Request
```shell-session
$ curl \
https://localhost:4646/v1/recommendation/cb80a13d-20d8-fb05-db3f-4ea0fe667b1b
```
### Sample Response
```json
{
"ID": "cb80a13d-20d8-fb05-db3f-4ea0fe667b1b",
"Region": "global",
"Namespace": "default",
"JobID": "example",
"JobVersion": 0,
"Group": "cache",
"Task": "redis",
"Resource": "MemoryMB",
"Value": 10,
"Current": 200,
"Meta": {
"nomad_autoscaler.count.original": 6,
"nomad_autoscaler.reason_history": [],
"nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c",
"num_evaluated_windows": 1148,
"window_size": 300000000000,
"nomad_autoscaler.count.capped": true
},
"Stats": {
"min": 2.6640625,
"p99": 6.51171875,
"max": 6.515625,
"mean": 4.816847859995009
},
"EnforceVersion": false,
"SubmitTime": 1603372587714807000,
"CreateIndex": 5193,
"ModifyIndex": 10437
}
```
## Apply and Dismiss Recommendations
This endpoint is used to apply and dismiss recommendations.
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `POST` | `/v1/recommendations/apply` | `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` | `namespace:submit-job` with `namespace:sentinel-override` if `PolicyOverride` set |
### Parameters
- `Apply` `(array<string>: nil)` - Specifies a set of recommendation IDs to be
applied. This results in Nomad applying the recommendation to the job
specification and performing a job register.
- `Dismiss` `(array<string>: nil)` - Specifies a set of recommendation IDs to be
dismissed. This results in Nomad deleting them from the state store.
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
will be overridden. This allows a recommendation to be applied when it would be
denied by a policy.
### Sample Payload
```json
{
"Apply": ["cb80a13d-20d8-fb05-db3f-4ea0fe667b1b"]
}
```
### Sample Request
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://localhost:4646/v1/recommendations/apply
```
### Sample Response
```json
{
"Errors": [],
"LastIndex": 0,
"RequestTime": 0,
"UpdatedJobs": [
{
"EvalCreateIndex": 51,
"EvalID": "3c91a755-f314-e2fb-500b-437ad08e13ea",
"JobID": "example",
"JobModifyIndex": 51,
"Namespace": "default",
"Recommendations": [
"cb80a13d-20d8-fb05-db3f-4ea0fe667b1b"
],
"Warnings": ""
}
]
}
```
## Create or Update a Recommendation
This endpoint is used to create or update a recommendation.
| Method | Path | Produces |
| ------ | -------------------- | ------------------ |
| `POST` | `/v1/recommendation` | `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` | `namespace:submit-recommendation` or `namespace:submit-job` |
### Parameters
- `ID` `(string: "")` - The ID of an existing recommendation to update.
- `Region` `(string: "")`- The Nomad region identifier which contains the job
that the recommendation is for. If omitted, this defaults to that of the Nomad
agent.
- `Namespace` `(string: "")`- The namespace within which the target job is running
within. If omitted, this defaults to `default`.
- `JobID` `(string: <required>)`- The job ID which this recommendation is for.
- `Group` `(string: <required>)`- The task group name within the job which this
recommendation is for.
- `Task` `(string: <required>)`- The task name within the task group which this
recommendation is for.
- `Resource` `(string: <required>)`- The resource that the recommendation is for.
Possible values are `CPU` and `MemoryMB`.
- `Value` `(int: <required>)`- The value recommendation for the resource. This
must met the minimum requirements which are `1` for `CPU` and `10` for `MemoryMB`.
- `Meta` `(map<string|...>: nil)`- JSON block that is persisted as part of the
recommendation providing arbitrary, useful information.
- `Stats` `(map<string|float64>: nil)` - A mapping of statistics that are persisted
as part of the recommendation providing insight into the recommendation
calculation.
- `EnforceVersion` `(bool: false)`- Indicates that the recommendation is only valid
for the current version of the job. Subsequent job updates will automatically
dismiss this recommendation.
### Sample Payload
```json
{
"Region": "global",
"Namespace": "default",
"JobID": "example",
"Group": "cache",
"Task": "redis",
"Resource": "MemoryMB",
"Value": 512,
"Meta": {
"nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c"
},
"Stats": {
"min": 2.6640625,
"p99": 6.51171875,
"max": 6.515625,
"mean": 4.816847859995009
}
}
```
### Sample Request
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://localhost:4646/v1/recommendation
```
### Sample Response
```json
{
"CreateIndex": 22,
"Current": 256,
"EnforceVersion": false,
"Group": "cache",
"ID": "47c97404-918f-8b19-873b-36d802f16f23",
"JobID": "example",
"JobVersion": 0,
"Meta": {
"nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c"
},
"ModifyIndex": 25,
"Namespace": "default",
"Region": "global",
"Resource": "MemoryMB",
"Stats": {
"mean": 4.816847859995009,
"min": 2.6640625,
"p99": 6.51171875,
"max": 6.515625
},
"SubmitTime": 1603444202372926000,
"Task": "redis",
"Value": 512
}
```