»Recommendation HTTP API

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

»List Recommendations

This endpoint lists all the currently available recommendations and provides optional filtering of that list.

MethodPathProduces
GET/v1/recommendationsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace: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.

MethodPathProduces
GET/v1/recommendation/:recommendation_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace: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.

MethodPathProduces
POST/v1/recommendations/applyapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace: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.

MethodPathProduces
POST/v1/recommendationapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnamespace: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
}