From e0c9d697de99edcc4fa72b7c8bc8c7d61f1d2fb7 Mon Sep 17 00:00:00 2001 From: James Rasell Date: Tue, 27 Oct 2020 16:23:38 +0100 Subject: [PATCH] docs: add recommendations API documentation. --- website/data/api-navigation.js | 1 + website/pages/api-docs/recommendations.mdx | 374 +++++++++++++++++++++ 2 files changed, 375 insertions(+) create mode 100644 website/pages/api-docs/recommendations.mdx diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index be14a6d60..dc4c17730 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -26,6 +26,7 @@ export default [ 'operator', 'plugins', 'quotas', + 'recommendations', 'regions', 'scaling-policies', 'search', diff --git a/website/pages/api-docs/recommendations.mdx b/website/pages/api-docs/recommendations.mdx new file mode 100644 index 000000000..20393f103 --- /dev/null +++ b/website/pages/api-docs/recommendations.mdx @@ -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: )`- 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: 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: 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: )`- The job ID which this recommendation is for. + +- `Group` `(string: )`- The task group name within the job which this + recommendation is for. + +- `Task` `(string: )`- The task name within the task group which this + recommendation is for. + +- `Resource` `(string: )`- The resource that the recommendation is for. + Possible values are `CPU` and `MemoryMB`. + +- `Value` `(int: )`- The value recommendation for the resource. This + must met the minimum requirements which are `1` for `CPU` and `10` for `MemoryMB`. + +- `Meta` `(map: nil)`- JSON block that is persisted as part of the + recommendation providing arbitrary, useful information. + +- `Stats` `(map: 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 +} +```