Recommendation HTTP API

The /recommendation endpoints are used to query and interact with Dynamic Application Sizing recommendations.

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 and required 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

$ curl \
    https://localhost:4646/v1/recommendations

$ curl \
    https://localhost:4646/v1/recommendations?namespace=*

$ curl \
    https://localhost:4646/v1/recommendations?namespace=*&job=example&group=cache&task=redis

Sample Response

[
  {
    "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 and required 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

$ curl \
    https://localhost:4646/v1/recommendation/cb80a13d-20d8-fb05-db3f-4ea0fe667b1b

Sample Response

{
  "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 and required 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

{
  "Apply": ["cb80a13d-20d8-fb05-db3f-4ea0fe667b1b"]
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/recommendations/apply

Sample Response

{
  "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 and required 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

{
  "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

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/recommendation

Sample Response

{
  "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
}