Recommendation HTTP API

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

Enterprise

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
}