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 +} +``` diff --git a/website/pages/api-docs/scaling-policies.mdx b/website/pages/api-docs/scaling-policies.mdx index 626c6986f..30edf189a 100644 --- a/website/pages/api-docs/scaling-policies.mdx +++ b/website/pages/api-docs/scaling-policies.mdx @@ -1,7 +1,7 @@ --- layout: api page_title: Scaling Policies - HTTP API -sidebar_title: Scaling Policies Beta +sidebar_title: Scaling Policies description: The /scaling/policy endpoints are used to list and view scaling policies. --- @@ -9,7 +9,7 @@ description: The /scaling/policy endpoints are used to list and view scaling pol The `/scaling/policies` and `/scaling/policy/` endpoints are used to list and view scaling policies. -## List Scaling Policies Beta +## List Scaling Policies This endpoint returns the scaling policies from all jobs. @@ -25,6 +25,16 @@ The table below shows this endpoint's support for | ---------------- | ----------------- | --------------------------------- | | `YES` | `all` | `namespace:list-scaling-policies` | +### Parameters + +- `job` `(string: "")`- Specifies the job ID to filter policies by. + +- `type` `(string: "")` - Specifies the type of scaling policy to filter by. In + the open source version of Nomad, `horizontal` is the only supported value. + Within Nomad Enterprise, `vertical_mem` and `vertical_cpu` are supported along + with `vertical`. The latter returns policies matching both `vertical_mem` and + `vertical_cpu`. + ### Sample Request ```shell-session @@ -32,25 +42,62 @@ $ curl \ https://localhost:4646/v1/scaling/policies ``` +```shell-session +$ curl \ + https://localhost:4646/v1/scaling/policies?job=example +``` + +```shell-session +$ curl \ + https://localhost:4646/v1/scaling/policies?type=vertical +``` + ### Sample Response ```json [ { - "CreateIndex": 10, + "ID": "b2c64295-4315-2fdc-6158-a27156808729", "Enabled": true, - "ID": "5e9f9ef2-5223-6d35-bac1-be0f3cb974ad", - "ModifyIndex": 10, + "Type": "vertical_cpu", "Target": { - "Group": "cache", + "Namespace": "default", "Job": "example", + "Group": "cache", + "Task": "redis" + }, + "CreateIndex": 1340, + "ModifyIndex": 1340 + }, + { + "ID": "c355d0ec-7aa1-2604-449d-4ec79c813d2c", + "Enabled": true, + "Type": "vertical_mem", + "Target": { + "Job": "example", + "Group": "cache", + "Task": "redis", "Namespace": "default" - } + }, + "CreateIndex": 1340, + "ModifyIndex": 1340 + }, + { + "ID": "31a53813-24df-b2ad-77dc-1b4bad4e7dca", + "Enabled": true, + "Type": "horizontal", + "Target": { + "Job": "example", + "Group": "cache", + "Namespace": "default" + }, + "CreateIndex": 1358, + "ModifyIndex": 1358 } ] ``` -## Read Scaling Policy Beta +## Read Scaling Policy This endpoint reads a specific scaling policy. @@ -85,6 +132,7 @@ $ curl \ "CreateIndex": 10, "Enabled": true, "ID": "5e9f9ef2-5223-6d35-bac1-be0f3cb974ad", + "Type": "horizontal", "Max": 10, "Min": 0, "ModifyIndex": 10, diff --git a/website/pages/docs/autoscaling/index.mdx b/website/pages/docs/autoscaling/index.mdx index 3733a9d6b..a0a2ad866 100644 --- a/website/pages/docs/autoscaling/index.mdx +++ b/website/pages/docs/autoscaling/index.mdx @@ -20,23 +20,41 @@ which provide guided learning on running the autoscaler. ## Horizontal Application Autoscaling -Horizontal application autoscaling is the process of automatically controlling the number of instances of an application -to have sufficient work throughput to meet service-level agreements (SLA). In -Nomad, horizontal application autoscaling can be achieved by modifying the number -of allocations in a task group based on the value of a relevant metric, such as -CPU and memory utilization or number of open connections. This is enabled by configuring -[autoscaling policies][autoscaling_policy] on individual Nomad jobs using the [`scaling` block][scaling_block]. +Horizontal application autoscaling is the process of automatically controlling the +number of instances of an application to have sufficient work throughput to meet +service-level agreements (SLA). In Nomad, horizontal application autoscaling can +be achieved by modifying the number of allocations in a task group based on the +value of a relevant metric, such as CPU and memory utilization or number of open +connections. This is enabled by configuring [autoscaling policies][autoscaling_policy] +on individual Nomad jobs using the [`scaling` block][scaling_block]. ## Horizontal Cluster Autoscaling -Horizontal cluster autoscaling is the process of adding or removing Nomad clients from a cluster to ensure there -is an appropriate amount of cluster resource for the scheduled applications. -This is achieved by interacting with remote providers to start or terminate new -Nomad clients based on metrics such as the remaining free schedulable CPU or memory. -Cluster scaling is enabled by configuring the [autoscaler agent](/docs/autoscaling/agent#dir) -with policies targeting the Nomad cluster. +Horizontal cluster autoscaling is the process of adding or removing Nomad clients +from a cluster to ensure there is an appropriate amount of cluster resource for +the scheduled applications. This is achieved by interacting with remote providers +to start or terminate new Nomad clients based on metrics such as the remaining +free schedulable CPU or memory. Cluster scaling is enabled by configuring the +[autoscaler agent](/docs/autoscaling/agent#dir) with policies targeting the Nomad +cluster. -[scaling_block]: /docs/job-specification/scaling +## Dynamic Application Sizing + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +Dynamic Application Sizing enables organizations to optimize the resource +consumption of applications using sizing recommendations from Nomad. It evaluates, +processes and stores historical task resource usage data, making recommendations +for CPU and Memory resource parameters. The recommendations can be calculated +using a number of different algorithms to ensure the recommendation best fits +the application profile. + +Dynamic Application Sizing can be enabled on an individual task by configuring +[autoscaling policies][autoscaling_policy] within the task stanza using the job +specification [`scaling` block][scaling_block]. + +[scaling_block]: /docs/job-specification/scaling#scaling-stanza [autoscaling_policy]: /docs/autoscaling/policy [autoscaler_github]: https://github.com/hashicorp/nomad-autoscaler [autoscaler_releases]: https://releases.hashicorp.com/nomad-autoscaler/ diff --git a/website/pages/docs/autoscaling/plugins/strategy.mdx b/website/pages/docs/autoscaling/plugins/strategy.mdx index ae70cb92f..fa8524e07 100644 --- a/website/pages/docs/autoscaling/plugins/strategy.mdx +++ b/website/pages/docs/autoscaling/plugins/strategy.mdx @@ -10,8 +10,8 @@ description: Strategy plugins compare the current state of the system against th Strategy plugins compare the current state of the system against the desired state defined by the operator in the scaling policy and generate an action that will bring the system closer to the desired state. In practical terms, strategies -receive the current count and a metric value for a task group or from servers in a -cluster, and output what the new count should be. +receive the current value and a metric value for a resource and output what the +new value should be. ## Target Value Strategy Plugin @@ -44,3 +44,108 @@ check { - `threshold` `(float: 0.01)` - Specifies how significant a change in the input metric should be considered. Small threshold values can lead to output fluctuation. + +## Dynamic Application Sizing Average Strategy Plugin + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +The `app-sizing-avg` plugin calculates the average value seen across the dataset. +The plugin applies an exponential weight decay to data, in order to give +more significance to recent data over older data. + +This plugin is only recommended for CPU values of workloads with very stable +resource usage levels, such as batch jobs. + +### Agent Configuration Options + +The `app-sizing-avg` plugin is automatically launched by Nomad Autoscaler +Enterprise and so the following setup is optional. + +```hcl +strategy "app-sizing-avg" { + driver = "app-sizing-avg" +} +``` + +### Policy Configuration Options + +```hcl +check "avg" { + strategy "app-sizing-avg" {} +} +``` + +## Dynamic Application Sizing Max Strategy Plugin + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +The `app-sizing-max` plugin calculates the maximum value seen for the target +resource within the available dataset. This plugin is ideally suited for memory +resources since workloads don’t release their memory too often and +underprovisioning could cause OOM errors. + +### Agent Configuration Options + +The `app-sizing-max` plugin is automatically launched by Nomad Autoscaler +Enterprise and so the following setup is optional. + +```hcl +strategy "app-sizing-max" { + driver = "app-sizing-max" +} +``` + +### Policy Configuration Options + +```hcl +check "max" { + strategy "app-sizing-max" {} +} +``` + +## Dynamic Application Sizing Percentile Strategy Plugin + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +The `app-sizing-percentile` plugin calculates its result based on a desired +percentile value from the dataset. + +The plugin applies an exponential weight decay to data, in order to give +more significance to recent data over older data. It also adjusts its calculation +based on the amount of resources used per unit of time. This load-adjusted +calculation results in values that are more likely to actually meet the usage +needs of the workload when compared to the traditional time-based percentile +calculation. + +This Dynamic Application Sizing plugin is the most versatile, since the percentile +level can be fine-tuned as needed. If your workload can withstand occasional OOM +errors gracefully, using a 98th percentile for memory instead of app-sizing-max +could result in smaller recommendations and subsequently more resource availability +for other tasks. A 95th to 90th percentile for CPU could have the same effect. + +### Agent Configuration Options + +The `app-sizing-percentile` plugin is automatically launched by Nomad Autoscaler +Enterprise and so the following setup is optional. + +```hcl +strategy "target-value" { + driver = "target-value" +} +``` + +### Policy Configuration Options + +```hcl +check "p95" { + strategy "app-sizing-percentile" { + percentile = "95" + } +} +``` + +- `percentile` `(int: 99)` - Specifies the percentile value to use when performing + the strategy calculation. diff --git a/website/pages/docs/autoscaling/plugins/target.mdx b/website/pages/docs/autoscaling/plugins/target.mdx index d71368d01..25d13917c 100644 --- a/website/pages/docs/autoscaling/plugins/target.mdx +++ b/website/pages/docs/autoscaling/plugins/target.mdx @@ -34,21 +34,87 @@ configure the scaling policy, the following section can be omitted as Nomad will populate them on job submission. ```hcl -check { +check "example-check" { ... target "nomad" { - Job = "example" - Group = "cache" + Namespace = "default" + Job = "example" + Group = "cache" } ... ``` -- `job` `(string: "")` - The job identifier which contains the task group to +- `Namespace` `(string: "")` - The namespace in which the job resides as defined + by the [`namespace` parameter][nomad_namespace_parameter] within the job + specification. + +- `Job` `(string: "")` - The job identifier which contains the task group to scale as defined within the job specification [`job` stanza][nomad_job_stanza]. -- `group` `(string: "")` - The name of the task group to scale as defined in the +- `Group` `(string: "")` - The name of the task group to scale as defined in the job specification [`group` stanza][nomad_group_stanza]. +## Dynamic Application Sizing Nomad Task Target + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +The `app-sizing-nomad` target plugin reports on the current task resource value +as well as submits recommendations to Nomad via the [recommendations API endpoint][nomad_recommendations_api] +based on the result of the Dynamic Application Sizing strategy calculations. + +### Agent Configuration Options + +The `app-sizing-nomad` plugin is automatically launched by Nomad Autoscaler +Enterprise and so the following setup is optional. + +```hcl +target "app-sizing-nomad" { + driver = "app-sizing-nomad" +} +``` + +### Policy Configuration Options + +If using the [Nomad job specification scaling stanza][nomad_scaling_stanza] to +configure the scaling policy for a task resource, the following section can be +omitted as Nomad will populate them on job submission. Please also refer to the +[Nomad Autoscaler policy documentation][nomad_autoscaler_policy] for additional +detail and guidance. + +```hcl +check "mem" { + ... + target "app-sizing-nomad" { + Namespace = "default" + Job = "example" + Group = "cache" + Task = "Redis" + Resource = "MemoryMB" + } + ... +``` + +- `Region` `(string: "")` - The region in which the job resides as defined + by the [`region` parameter][nomad_region_parameter] within the job specification. + +- `Namespace` `(string: "")` - The namespace in which the job resides as defined + by the [`namespace` parameter][nomad_namespace_parameter] within the job + specification. + +- `Job` `(string: "")` - The job identifier which contains the task group to + scale as defined within the job specification [`job` stanza][nomad_job_stanza]. + +- `Group` `(string: "")` - The name of the task group to scale as defined in the + job specification [`group` stanza][nomad_group_stanza]. + +- `Task` `(string: "")` - The name of the task to scale as defined in the job + specification [`task` stanza][nomad_task_stanza]. + +- `Resource` `(string: "")` - The resource to scale as defined by the job + specification [`resource` stanza][nomad_resource_stanza]. Supports either `CPU` + or `MemoryMB`. + ## AWS AutoScaling Group Target The AWS ASG target plugin allows for the scaling of the Nomad cluster clients @@ -125,7 +191,7 @@ node { ### Policy Configuration Options ```hcl -check { +check "hashistack-allocated-cpu" { ... target "aws-asg" { aws_asg_name = "hashistack-client-asg" @@ -157,3 +223,9 @@ check { [aws_autoscaling]: https://aws.amazon.com/autoscaling/ [vault_aws_backend]: https://www.vaultproject.io/docs/secrets/aws [nomad_node_purge]: /api-docs/nodes#purge-node +[nomad_recommendations_api]: /api-docs/recommendations +[nomad_task_stanza]: /docs/job-specification/task#task-stanza +[nomad_resource_stanza]: /docs/job-specification/resources#resources-stanza +[nomad_namespace_parameter]: /docs/job-specification/job#namespace +[nomad_region_parameter]: /docs/job-specification/job#region +[nomad_autoscaler_policy]: /docs/autoscaling/policy diff --git a/website/pages/docs/autoscaling/policy.mdx b/website/pages/docs/autoscaling/policy.mdx index 53c396859..8866d6ef5 100644 --- a/website/pages/docs/autoscaling/policy.mdx +++ b/website/pages/docs/autoscaling/policy.mdx @@ -9,9 +9,10 @@ description: > # Nomad Autoscaler Scaling Policies -Nomad Autoscaler scaling policies can be configured via the -[task group `scaling` stanza][jobspec_scaling_stanza] or by configuration -files stored on disk. +Nomad Autoscaler scaling policies can be configured via the [`scaling` stanza][jobspec_scaling_stanza] +or by configuration files stored on disk. The options available differ whether +you are performing horizontal application/cluster scaling or Dynamic Application +Sizing. ## Top Level Options @@ -24,7 +25,10 @@ files stored on disk. - `max` - The maximum running count of the targeted resource. This can be 0 or any positive integer. -## `policy` Options +## Task Group and Cluster Scaling `policy` Options + +The following options are available when using the Nomad Autoscaler to perform +horizontal application scaling or horizontal cluster scaling. - `cooldown` - A time interval after a scaling action during which no additional scaling will be performed on the resource. It should be provided as a duration @@ -88,6 +92,68 @@ policy { } ``` +## Task (DAS) `policy` Options + +~> **Enterprise Only!** This functionality only exists in Nomad Autoscaler +Enterprise. This is not present in the open source version of Nomad Autoscaler. + +The following options are available when using the Nomad Autoscaler Enterprise +to perform Dynamic Application Sizing recommendations for task resources. When +using the [`scaling` stanza][jobspec_scaling_stanza] for Dynamic Application +Sizing, the stanza requires a label to identify which resource it relates to. It +currently supports `cpu` and `mem` labels, examples of which can be seen below. + +- `cooldown` - A time interval after a scaling action during which no additional + scaling will be performed on the resource. It should be provided as a duration + (e.g.: `"5s"`, `"1m"`). If omitted the configuration value + [policy_default_cooldown][policy_default_cooldown_agent] from the agent will + be used. + +- `evaluation_interval` - Defines how often the policy is evaluated by the + Autoscaler. It should be provided as a duration (e.g.: `"5s"`, `"1m"`). If + omitted the configuration value [default_evaluation_interval][eval_interval_agent] + from the agent will be used. + +- `target` - Defines where the autoscaling target is running. Detailed information + on the configuration options can be found on the [Target Plugins][target_plugin_docs] + page. + +- `check` - Specifies one check to be executed when determining if a recommendation + is required. Only one check is permitted per scaling block within Dynamic + Application Sizing. + +## `check` Options + +- `strategy` - The strategy to use, and it's configuration when calculating the + desired state based on the current value and the available historic data. Detailed + information on the configuration options can be found on the + [Strategy Plugins][strategy_plugin_docs] page. + +### Example + +The following examples are minimal blocks which can be used to configure CPU and +Memory based sizing recommendations for a Nomad job task. + +```hcl +scaling "cpu" { + policy { + check "96pct" { + strategy "app-sizing-percentile" { + percentile = "96" + } + } + } +} + +scaling "mem" { + policy { + check "max" { + strategy "app-sizing-max" {} + } + } +} +``` + [policy_default_cooldown_agent]: /docs/autoscaling/agent#default_cooldown [eval_interval_agent]: /docs/autoscaling/agent#default_evaluation_interval [target_plugin_docs]: /docs/autoscaling/plugins/target diff --git a/website/pages/docs/enterprise.mdx b/website/pages/docs/enterprise.mdx index 3472fa5b9..e1260ceda 100644 --- a/website/pages/docs/enterprise.mdx +++ b/website/pages/docs/enterprise.mdx @@ -97,9 +97,22 @@ features such as Multiregion Deployments. federated regions. This includes the ability to control the order of rollouts and how each region will behave in the event of a deployment failure. +### Dynamic Application Sizing + +Dynamic Application Sizing enables organizations to optimize the resource +consumption of applications using sizing recommendations from Nomad. This +feature builds on Nomad [autoscaling capabilities] to remove the trial-and-error +routine of manually setting resource requirements. DAS comprises support for +vertical [scaling policies], a new API and UI for reviewing recommended job +changes, and a collection of Nomad Autoscaler plugins informed by best-practice +statistical measures. + + ## Try Nomad Enterprise -Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or request a trial -of Nomad Enterprise. +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or +request a trial of Nomad Enterprise. [multiregion deployments]: /docs/job-specification/multiregion +[autoscaling capabilities]: /docs/autoscaling +[scaling policies]: /docs/autoscaling/policy