375 lines
10 KiB
Plaintext
375 lines
10 KiB
Plaintext
---
|
|
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.
|
|
|
|
<EnterpriseAlert>
|
|
This API endpoint and functionality only exists in
|
|
Nomad Enterprise. This is not present in the open source version of Nomad.
|
|
</EnterpriseAlert>
|
|
|
|
## 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
|
|
}
|
|
```
|