diff --git a/website/content/docs/autoscaling/plugins/apm/datadog.mdx b/website/content/docs/autoscaling/plugins/apm/datadog.mdx new file mode 100644 index 000000000..c9b58a7fe --- /dev/null +++ b/website/content/docs/autoscaling/plugins/apm/datadog.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Datadog' +description: The "datadog" APM plugin queries Datadog for metrics. +--- + +# Datadog APM Plugin + +The `datadog` APM plugin allows using [time series][datadog_timeseries] data +from [Datadog][datadog_homepage] to make scaling decisions. + +## Agent Configuration Options + +```hcl +apm "datadog" { + driver = "datadog" + + config = { + dd_api_key = "" + dd_app_key = "" + } +} +``` + +- `dd_api_key` `(string: )` - The Datadog API key to use for + authentication. + +- `dd_app_key` `(string: )` - The Datadog application key to use for + authentication. + +The Datadog plugin can also read its configuration options via environment +variables. The accepted keys are `DD_API_KEY` and `DD_APP_KEY`. The agent +configuration parameters take precedence over the environment variables. + +## Policy Configuration Options + +```hcl +check { + source = "datadog" + query = "avg:proxy.backend.response.time{proxy-service:web-app}" + # ... +} +``` + +[datadog_homepage]: https://www.datadoghq.com/ +[datadog_timeseries]: https://docs.datadoghq.com/api/v1/metrics/#query-timeseries-points diff --git a/website/content/docs/autoscaling/plugins/apm/index.mdx b/website/content/docs/autoscaling/plugins/apm/index.mdx new file mode 100644 index 000000000..085f0a787 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/apm/index.mdx @@ -0,0 +1,12 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: APM' +description: APM plugins provide metric data points describing the resources current state. +--- + +# APM Plugins + +Application Performance Management (APM) tools are used to store metrics about +an applications performance and its current state. The APM plugins are +responsible for querying an APM and returning a time series which will be used +to determine if scaling should occur. diff --git a/website/content/docs/autoscaling/plugins/apm.mdx b/website/content/docs/autoscaling/plugins/apm/nomad.mdx similarity index 51% rename from website/content/docs/autoscaling/plugins/apm.mdx rename to website/content/docs/autoscaling/plugins/apm/nomad.mdx index dd20187f9..2551d54ce 100644 --- a/website/content/docs/autoscaling/plugins/apm.mdx +++ b/website/content/docs/autoscaling/plugins/apm/nomad.mdx @@ -1,89 +1,17 @@ --- layout: docs -page_title: APM -description: APM plugins provide metric data points describing the resources current state. +page_title: 'Autoscaling Plugins: Nomad API' +description: The "nomad-apm" APM plugin queries the Nomad API for metrics. --- -# APM Plugins - -APMs are used to store metrics about an applications performance and current -state. The APM (Application Performance Management) plugin is responsible for -querying the APM and returning a value which will be used to determine if -scaling should occur. - -## Prometheus APM Plugin - -Use [Prometheus][prometheus_io] metrics to scale your Nomad job task groups or -cluster. - -### Agent Configuration Options - -```hcl -apm "prometheus" { - driver = "prometheus" - - config = { - address = "http://prometheus.my.endpoint.io:9090" - } -} -``` - -- `address` `(string: "http://127.0.0.1:9090")` - The address of the Prometheus - endpoint used to perform queries. - -### Policy Configuration Options - -```hcl -check { - source = "prometheus" - query = "avg((haproxy_server_current_sessions{backend=\"http_back\"}) and (haproxy_server_up{backend=\"http_back\"} == 1))" - ... -} -``` - -## Datadog APM Plugin - -The [Datadog][datadog_homepage] APM allows using [time series][datadog_timeseries] -data to make scaling decisions. - -### Agent Configuration Options - -```hcl -apm "datadog" { - driver = "datadog" - - config = { - dd_api_key = "" - dd_app_key = "" - } -} -``` - -- `dd_api_key` `(string: "")` - The Datadog API key to use for authentication. -- `dd_app_key` `(string: "")` - The Datadog APP key to use for authentication. - -The Datadog plugin can also read its configuration options via environment -variables. The accepted keys are `DD_API_KEY` and `DD_APP_KEY`. The agent -configuration parameters take precedence over the environment variables. - -### Policy Configuration Options - -```hcl -check { - source = "datadog" - query = "avg:proxy.backend.response.time{proxy-service:web-app}" - ... -} -``` - -## Nomad APM Plugin +# Nomad APM Plugin The Nomad APM plugin allows querying the Nomad API for metric data. This provides an immediate starting point without addition applications but comes at the price of efficiency. When using this APM, it is advised to monitor Nomad carefully ensuring it is not put under excessive load pressure. -### Agent Configuration Options +## Agent Configuration Options ```hcl apm "nomad-apm" { @@ -114,7 +42,7 @@ namespace "default" { } ``` -### Policy Configuration Options - Task Groups +## Policy Configuration Options - Task Groups The Nomad APM allows querying Nomad to understand the current resource usage of a task group. @@ -123,7 +51,7 @@ a task group. check { source = "nomad-apm" query = "avg_cpu" - ... + # ... } ``` @@ -149,7 +77,7 @@ The metric value can be: - `memory` - Memory usage as reported by the `nomad.client.allocs.memory.usage` metric. -### Policy Configuration Options - Client Nodes +## Policy Configuration Options - Client Nodes The Nomad APM allows querying Nomad to understand the current allocated resource as a percentage of the total available. @@ -176,8 +104,4 @@ The metric value can be: - `memory` - allocated memory as reported by calculating total allocatable against the total allocated by the scheduler. -[prometheus_io]: https://prometheus.io/ -[prometheus_scaler_function]: https://prometheus.io/docs/prometheus/latest/querying/functions/#scalar [nomad_telemetry_stanza]: /docs/configuration/telemetry#inlinecode-publish_allocation_metrics -[datadog_homepage]: https://www.datadoghq.com/ -[datadog_timeseries]: https://docs.datadoghq.com/api/v1/metrics/#query-timeseries-points diff --git a/website/content/docs/autoscaling/plugins/apm/prometheus.mdx b/website/content/docs/autoscaling/plugins/apm/prometheus.mdx new file mode 100644 index 000000000..89de233c7 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/apm/prometheus.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Prometheus' +description: The "prometheus" APM plugin queries a Prometheus server. +--- + +# Prometheus APM Plugin + +The `prometheus` APM plugin allows querying for metrics stored in a +[Prometheus][prometheus_io] server. + +## Agent Configuration Options + +```hcl +apm "prometheus" { + driver = "prometheus" + + config = { + address = "http://prometheus.my.endpoint.io:9090" + } +} +``` + +- `address` `(string: "http://127.0.0.1:9090")` - The address of the Prometheus + endpoint used to perform queries. + +## Policy Configuration Options + +```hcl +check { + source = "prometheus" + query = "avg((haproxy_server_current_sessions{backend=\"http_back\"}))" + # ... +} +``` + +[prometheus_io]: https://prometheus.io/ diff --git a/website/content/docs/autoscaling/plugins/external/index.mdx b/website/content/docs/autoscaling/plugins/external/index.mdx index d35eee6d5..89f5583de 100644 --- a/website/content/docs/autoscaling/plugins/external/index.mdx +++ b/website/content/docs/autoscaling/plugins/external/index.mdx @@ -6,9 +6,9 @@ description: A list of community-supported Autoscaler Plugins. # Community Supported -If you have authored an autoscaler plugin that you believe will be useful to the -broader Nomad community and you are committed to maintaining the plugin, please -file a PR to add your plugin to this page. +If you have authored an autoscaler plugin that you believe will be useful to +the broader Nomad community and you are committed to maintaining the plugin, +please file a PR to add your plugin to this page. For details on authoring an autoscaler plugin, please refer to the [plugin authoring guide][plugin_guide]. @@ -17,8 +17,8 @@ Below is a list of community-support plugins available for the Nomad autoscaler. ## Target Plugins -- [OpenStack Senlin][senlin] - [DigitalOcean Droplets][do-droplets] +- [OpenStack Senlin][senlin] [plugin_guide]: /docs/autoscaling/internals/plugins [senlin]: https://github.com/dkt26111/nomad-senlin-autoscaler diff --git a/website/content/docs/autoscaling/plugins/index.mdx b/website/content/docs/autoscaling/plugins/index.mdx index a8c0b657c..411409381 100644 --- a/website/content/docs/autoscaling/plugins/index.mdx +++ b/website/content/docs/autoscaling/plugins/index.mdx @@ -1,6 +1,6 @@ --- layout: docs -page_title: Plugins +page_title: Autoscaling Plugins description: Plugins are used to architect the Nomad Autoscaler into distinct areas. --- diff --git a/website/content/docs/autoscaling/plugins/strategy.mdx b/website/content/docs/autoscaling/plugins/strategy.mdx deleted file mode 100644 index 85866cfbb..000000000 --- a/website/content/docs/autoscaling/plugins/strategy.mdx +++ /dev/null @@ -1,213 +0,0 @@ ---- -layout: docs -page_title: Strategy -description: Strategy plugins compare the current state of the system against the desired state. ---- - -# Strategy Plugins - -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 value and a metric value for a resource and output what the -new value should be. - -## Target Value Strategy Plugin - -The target value strategy plugin will perform count calculations in order to keep -the value resulting from the APM query at or around a specified target. - -### Agent Configuration Options - -```hcl -strategy "target-value" { - driver = "target-value" -} -``` - -### Policy Configuration Options - -```hcl -check "target-value-check" { - ... - strategy "target-value" { - target = 20 - threshold = 0.0001 - } - ... -``` - -- `target` `(float: )` - Specifies the metric value the Autoscaler - should try to meet. - -- `threshold` `(float: 0.01)` - Specifies how significant a change in the input - metric should be considered. Small threshold values can lead to output - fluctuation. - -## Fixed Value Strategy Plugin - -The fixed value strategy receives a count value as an input configuration option -and returns a scaling action whose count is set to the same value. This strategy is -useful in situations where there’s a known baseline for the infrastructure that -does not change often. - -### Agent Configuration Options - -```hcl -strategy "fixed-value" { - driver = "fixed-value" -} -``` - -### Policy Configuration Options - -```hcl -check "fixed-value-check" { - ... - strategy "fixed-value" { - value = 3 - } - ... -``` - -- `value` `(int: )` - The value used by the Nomad Autoscaler to set the - target count. - -## Pass-Through Strategy Plugin - -The pass-through strategy is a very simple, yet useful strategy. It does not -add any extra computation on top of the metric query result, and instead uses -the APM query result as the scaling count. It doesn't have any configuration -options. - -This allows the Nomad Autoscaler to be integrated into systems where the -scaling computation is done externally like an edge router, or easily derived -from a query such as running one allocation per item in a queue. - -### Agent Configuration Options - -```hcl -strategy "pass-through" { - driver = "pass-through" -} -``` - -### Policy Configuration Options - -```hcl -check "pass-through-check" { - ... - strategy "pass-through" {} - ... -``` - -## Dynamic Application Sizing Average Strategy Plugin - - - 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 - - - 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 - - - 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/content/docs/autoscaling/plugins/strategy/app-sizing-avg.mdx b/website/content/docs/autoscaling/plugins/strategy/app-sizing-avg.mdx new file mode 100644 index 000000000..e595f93d4 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/app-sizing-avg.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Dynamic Application Sizing Average' +description: The "app-sizing-avg" strategy plugin uses the historical average usage to set resource recommendations. +--- + +# Dynamic Application Sizing Average Strategy Plugin + + + 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 +historical metrics dataset. The plugin applies an exponential weight decay to +the 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" {} +} +``` + +The `app-sizing-avg` plugin doesn't have any configuration. diff --git a/website/content/docs/autoscaling/plugins/strategy/app-sizing-max.mdx b/website/content/docs/autoscaling/plugins/strategy/app-sizing-max.mdx new file mode 100644 index 000000000..708a3d334 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/app-sizing-max.mdx @@ -0,0 +1,38 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Dynamic Application Sizing Max' +description: The "app-sizing-max" strategy plugin uses the historical maximum usage to set resource recommendations. +--- + +# Dynamic Application Sizing Max Strategy Plugin + + + 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" {} +} +``` + +The `app-sizing-max` plugin doesn't have any configuration. diff --git a/website/content/docs/autoscaling/plugins/strategy/app-sizing-percentile.mdx b/website/content/docs/autoscaling/plugins/strategy/app-sizing-percentile.mdx new file mode 100644 index 000000000..a21aec2d8 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/app-sizing-percentile.mdx @@ -0,0 +1,52 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Dynamic Application Sizing Percentile' +description: The "app-sizing-percentile" strategy plugin uses percentile value of the historical usage to set resource recommendations. +--- + +# Dynamic Application Sizing Percentile Strategy Plugin + + + 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/content/docs/autoscaling/plugins/strategy/fixed-value.mdx b/website/content/docs/autoscaling/plugins/strategy/fixed-value.mdx new file mode 100644 index 000000000..46b941484 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/fixed-value.mdx @@ -0,0 +1,35 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Fixed Value' +description: The "fixed-value" strategy plugin sets a pre-defined value when scaling. +--- + +# Fixed Value Strategy Plugin + +The `fixed-value` strategy receives a count value as an input configuration +option and returns a scaling action whose count is set to the same value. This +strategy is useful in situations where there’s a known baseline for the +infrastructure that does not change often. + +## Agent Configuration Options + +```hcl +strategy "fixed-value" { + driver = "fixed-value" +} +``` + +## Policy Configuration Options + +```hcl +check "fixed-value-check" { + # ... + strategy "fixed-value" { + value = 3 + } + # ... +} +``` + +- `value` `(int: )` - The value used by the Nomad Autoscaler to set + the target count. diff --git a/website/content/docs/autoscaling/plugins/strategy/index.mdx b/website/content/docs/autoscaling/plugins/strategy/index.mdx new file mode 100644 index 000000000..31f32bb26 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/index.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Strategy' +description: Strategy plugins compare the current state of the system against the desired state. +--- + +# Strategy Plugins + +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 value and a metric value for a resource and output what the +new value should be. diff --git a/website/content/docs/autoscaling/plugins/strategy/pass-through.mdx b/website/content/docs/autoscaling/plugins/strategy/pass-through.mdx new file mode 100644 index 000000000..f10a2e47e --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/pass-through.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Pass-Through' +description: The "pass-through" strategy plugin passes the query result directly to the target. +--- + +# Pass-Through Strategy Plugin + +The `pass-through` strategy is a very simple, yet useful strategy. It does not +add any extra computation on top of the metric query result, and instead uses +the APM query result as the scaling count. It doesn't have any configuration +options. + +This allows the Nomad Autoscaler to be integrated into systems where the +scaling computation is done externally like an edge router, or easily derived +from a query such as running one allocation per item in a queue. + +## Agent Configuration Options + +```hcl +strategy "pass-through" { + driver = "pass-through" +} +``` + +## Policy Configuration Options + +```hcl +check "pass-through-check" { + # ... + strategy "pass-through" {} + # ... +} +``` + +The `pass-through` plugin doesn't have any configuration. diff --git a/website/content/docs/autoscaling/plugins/strategy/target-value.mdx b/website/content/docs/autoscaling/plugins/strategy/target-value.mdx new file mode 100644 index 000000000..7be659517 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/target-value.mdx @@ -0,0 +1,38 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Target Value' +description: The "target-value" strategy plugin tracks a target metric value. +--- + +# Target Value Strategy Plugin + +The `target-value` strategy plugin will perform count calculations in order to +keep the value resulting from the APM query at or around a specified target. + +## Agent Configuration Options + +```hcl +strategy "target-value" { + driver = "target-value" +} +``` + +## Policy Configuration Options + +```hcl +check "target-value-check" { + # ... + strategy "target-value" { + target = 20 + threshold = 0.0001 + } + # ... +} +``` + +- `target` `(float: )` - Specifies the metric value the Autoscaler + should try to meet. + +- `threshold` `(float: 0.01)` - Specifies how significant a change in the input + metric should be considered. Small threshold values can lead to output + fluctuation. diff --git a/website/content/docs/autoscaling/plugins/strategy/threshold.mdx b/website/content/docs/autoscaling/plugins/strategy/threshold.mdx new file mode 100644 index 000000000..bbfc4d8ad --- /dev/null +++ b/website/content/docs/autoscaling/plugins/strategy/threshold.mdx @@ -0,0 +1,78 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Threshold' +description: The "threshold" strategy plugin uses metric value tiers to define scaling actions. +--- + +# Threshold Strategy Plugin + +The `threshold` strategy defines a range of metric values with a lower and an +upper bound, and an action to take when the current metric value is considered +to be within bounds. + +Multiple tiers can be defined by declaring more than one `check` in the +same scaling policy. If there is any overlap between the bounds, the [safest +`check`][internals_check] will be used. + +## Agent Configuration Options + +```hcl +strategy "threshold" { + driver = "threshold" +} +``` + +## Policy Configuration Options + +```hcl +policy { + # ... + check "high-memory-usage" { + # ... + strategy "threshold" { + upper_bound = 100 + lower_bound = 70 + delta = 1 + } + } + + check "low-memory-traffic" { + # ... + strategy "threshold" { + upper_bound = 30 + lower_bound = 0 + delta = -1 + } + } + # ... +} +``` + +- `lower_bound` `(float: )` - The minimum value a metric must have + to be considered with bounds. + +- `upper_bound` `(float: )` - The maximum value a metric must have + to be considered within bounds. + +- `delta` `(int: )` - Specifies the relative amount to add (positive + value) or remove (negative value) from the current target count. Conflicts + with `percentage` and `value`. + +- `percentage` `(float: )` - Specifies a percentage value by which + the current count should be increased (positive value) or decreased (negative + value). Conflicts with `delta` and `value`. + +- `value` `(int: )` - Specifies an absolute value that should be set + as the new target count. Conflicts with `delta` and `percentage`. + +- `within_bounds_trigger` `(int: 5)` - The number of data points in the query + result time series that must be within the bound valus to trigger the action. + +At least one of `lower_bound` or `upper_bound` must be defined. If +`lower_bound` is not defined, any value below `upper_bound` is considered +within bounds. Similarly, if `upper_bound` is not defined, any value above +`lower_bound` will be considered within bounds. + +One, and only one, of `delta`, `percentage`, or `value` must be defined. + +[internals_check]: /docs/autoscaling/internals/checks diff --git a/website/content/docs/autoscaling/plugins/target.mdx b/website/content/docs/autoscaling/plugins/target.mdx deleted file mode 100644 index 646a7ea50..000000000 --- a/website/content/docs/autoscaling/plugins/target.mdx +++ /dev/null @@ -1,474 +0,0 @@ ---- -layout: docs -page_title: Target -description: Target plugins determine where the resource to be autoscaled is located. ---- - -# Target Plugins - -Target Plugins determine where the resource to be autoscaled is located. All -target plugins support the `dry-run` policy config parameter which allows a policy -to be evaluated, but will noop any suggested changes. - -Below is a list of plugins you can use with the Nomad Autoscaler: - -- [Nomad Task Group][nomad_task_group_target] -- [Dynamic Application Sizing Nomad Task][das_task_target] -- [AWS AutoScaling Group][aws_asg_target] -- [Azure Virtual Machine Scale Set][azure_vmss_target] -- [Google Cloud Platform Managed Instance Groups][gcp_mig_target] - -## Nomad Task Group Target - -The Nomad task group target indicates the scalable resource is a Nomad job -running on a Nomad cluster. - -### Agent Configuration Options - -The Nomad target is automatically launched by the Nomad Autoscaler and so the -following setup is optional. - -```hcl -target "nomad" { - driver = "nomad" -} -``` - -### Policy Configuration Options - -If using the [Nomad job specification scaling stanza][nomad_scaling_stanza] to -configure the scaling policy, the following section can be omitted as Nomad will -populate them on job submission. - -```hcl -check "example-check" { - ... - target "nomad" { - Namespace = "default" - Job = "example" - Group = "cache" - } - ... -``` - -- `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]. - -## Dynamic Application Sizing Nomad Task Target - - - 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 -via manipulating [AWS AutoScaling Groups][aws_autoscaling]. - -### Agent Configuration Options - -To use the AWS ASG target plugin, the agent configuration needs to be populated -with the appropriate target block. Authentication to the AWS API can be supplied -in a number of ways including EC2 instance roles. It is recommended, if possible -to use the [Vault AWS Secrets engine][vault_aws_backend] for supplying access -credentials to the plugin. Credentials should be injected into the configuration -via a template rather than as environment variables. This ensures the credentials -are passed only to the plugin, rather than being available for all plugins and -the agent process. - -The IAM policy required for the AWS ASG plugin to function properly is detailed -below. - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "", - "Effect": "Allow", - "Action": [ - "autoscaling:UpdateAutoScalingGroup", - "autoscaling:DescribeScalingActivities", - "autoscaling:DescribeAutoScalingGroups", - "autoscaling:CreateOrUpdateTags", - "autoscaling:TerminateInstanceInAutoScalingGroup" - ], - "Resource": "*" - } - ] -} -``` - -```hcl -target "aws-asg" { - driver = "aws-asg" - config = { - aws_region = "eu-west-3" - aws_access_key_id = "AKIAIOSFODNN7EXAMPLE" - aws_secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" - } -} -``` - -When using a Nomad cluster with ACLs enabled, the plugin will require an ACL token which provides -the following permissions: - -```hcl -node { - policy = "write" -} -``` - -- `aws_region` `(string: "us-east-1")` - The [AWS region][aws_region] identifier - to connect to and where resources should be managed. - -- `aws_access_key_id` `(string: "")` - The AWS access key ID used to authenticate - with the AWS API. - -- `aws_secret_access_key` `(string: "")` - The AWS secret key ID used to authenticate - with the AWS API. - -- `aws_session_token` `(string: "")` - The AWS session token used to authenticate - with the AWS API. - -### Policy Configuration Options - -```hcl -check "hashistack-allocated-cpu" { - ... - target "aws-asg" { - aws_asg_name = "hashistack-client-asg" - node_class = "hashistack" - node_drain_deadline = "5m" - node_purge = "true" - } - ... -``` - -- `aws_asg_name` `(string: )` - The name of the AWS AutoScaling Group to - interact with when performing scaling actions. - -- `datacenter` `(string: "")` - The Nomad client [datacenter][datacenter] identifier - used to group nodes into a pool of resource. Conflicts with `node_class`. - -- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] identifier - used to group nodes into a pool of resource. Conflicts with `datacenter`. - -- `node_drain_deadline` `(duration: "15m")` The Nomad [drain deadline][nomad_node_drain_deadline] - to use when performing node draining actions. **Please note that the default value - for this setting differs from Nomad's default of 1h.** - -- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to control if - system jobs should be stopped when performing node draining actions. - -- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad clients should - be [purged][nomad_node_purge] when performing scale in actions. - -- `node_selector_strategy` `(string: "least_busy")` The strategy to use when selecting - nodes for termination. Please see the [node selector strategy][node_selector_strategy] - documentation for more detailed information. - -## Azure Virtual Machine Scale Set Target - -The Azure VMSS target plugin allows for the scaling of the Nomad cluster clients -via manipulating [Azure Virtual Machine Scale Sets][azure_virtual_machine_scale_sets]. - -~> The Azure VMSS target plugin requires Azure fingerprinting, which became -available in Nomad 1.0. If you are running a previous version of Nomad you will -to set a [meta tag][client_meta_tag] in all of your nodes. - -### Agent Configuration Options - -To use the Azure VMSS target plugin, the agent configuration needs to be populated -with the appropriate target block. Authentication to the Azure API can be supplied -in a number of ways. - -#### Virtual Machine Identities - -When using [virtual machine identities][vm_identity] you will need to provide a -user-managed identity with the `Contributor` role and set the `subscription_id` -in the Autoscaler configuration file: - -```hcl -target "azure-vmss" { - driver = "azure-vmss" - config = { - subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" - } -} -``` - -#### Configuration file - -Credentials should be injected into the configuration via a template rather -than as environment variables. This ensures the credentials are passed only to -the plugin, rather than being available for all plugins and the agent process. -It is recommended, if possible to use the -[Vault Azure Secrets engine][vault_azure_backend] for supplying access -credentials to the plugin. - -```hcl -target "azure-vmss" { - driver = "azure-vmss" - config = { - tenant_id = "02e99e69-91b0-4d0a-bd61-bf5c08fbfbab" - client_id = "34c276fa-2a74-4cf9-9fce-4e60642274cb" - secret_access_key = "ThisIrznTIS_~FAKEj4X93FTyAgilUC511" - subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" - } -} -``` - -- `tenant_id` `(string: "")` - The ID of the tenant to authenticate to. - -- `client_id` `(string: "")` - The app ID of the user-assigned identity in Azure - Active Directory. - -- `secret_access_key` `(string: "")` - The secret key ID used to authenticate - with the Azure API. - -- `subscription_id` `(string: "")` - The ID of the subscription to authenticate - to. - -#### Nomad ACL - -When using a Nomad cluster with ACLs enabled, the plugin will require an ACL token -which provides the following permissions: - -```hcl -node { - policy = "write" -} -``` - -### Policy Configuration Options - -```hcl -check "clients-azure-vmss" { - ... - target "azure-vmss" { - resource_group = "prod" - vm_scale_set = "hashistack-client-set" - node_class = "hashistack" - node_drain_deadline = "5m" - node_purge = "true" - } - ... -``` - -- `resource_group` `(string: )` - The name of the [Azure resource group][azure_resource_group] - within which the virtual machine scale set resides. - -- `vm_scale_set` `(string: )` - The name of the Azure virtual machine - scale set to interact with when performing scaling actions. - -- `datacenter` `(string: "")` - The Nomad client [datacenter][datacenter] identifier - used to group nodes into a pool of resource. Conflicts with `node_class`. - -- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] identifier - used to group nodes into a pool of resource. Conflicts with `datacenter`. - -- `node_drain_deadline` `(duration: "15m")` The Nomad [drain deadline][nomad_node_drain_deadline] - to use when performing node draining actions. **Please note that the default value - for this setting differs from Nomad's default of 1h.** - -- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to control if - system jobs should be stopped when performing node draining actions. - -- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad clients should - be [purged][nomad_node_purge] when performing scale in actions. - -- `node_selector_strategy` `(string: "least_busy")` The strategy to use when selecting - nodes for termination. Please see the [node selector strategy][node_selector_strategy] - documentation for more detailed information. - -### Client meta tag - -The Azure VMSS target plugin requires Nomad 1.0 for Azure fingerprinting. -Alternatively, you can set a [client meta tag][client_meta_tag_docs] called -`unique.platform.azure.name` with the value being the Azure VMSS node name. -This can be retrieved programatically via the -[Azure Instance Metadata service][azure_instance_metadata]. - -## Google Cloud Platform Managed Instance Groups Target - -The GCP MIG target plugin allows for the scaling of the Nomad cluster clients -via manipulating [Google Cloud Platform Managed Instance Groups][gcp_migs]. The -plugin supports both regional and zonal groups. - -### Agent Configuration Options - -The plugin uses the official Google Cloud Golang SDK. This means it supports the -common ways of [providing credentials to Google Cloud][gcp_credentials]. It is -recommended, if possible to use the [Vault GCP Secrets engine][vault_gcp_backend] -for supplying access credentials to the plugin. Credentials should be injected -into the configuration via a template rather than as environment variables. This -ensures the credentials are passed only to the plugin, rather than being available -for all plugins and the agent process. - -```hcl -target "gcp-mig" { - driver = "gcp-mig" - config = { - credentials = "local/creds.json" - } -} -``` - -- `credentials` `(string: "")` - This is specified as the path to a Google Cloud - credentials file, typically for a service account. - -When using a Nomad cluster with ACLs enabled, the plugin will require an ACL token -which provides the following permissions: - -```hcl -node { - policy = "write" -} -``` - -### Policy Configuration Options - -```hcl -check "hashistack-allocated-cpu" { - ... - target "gcp-mig" { - project = "hashistack-demo" - region = "us-west1" - mig_name = "nomad-client-hashistack" - node_class = "hashistack" - node_drain_deadline = "5m" - node_purge = "true" - } - ... -``` - -- `project` `(string: )` - The [Google Cloud Platform project ID][gcp_projects] - within which the managed instance group is running. - -- `region` `(string: "")` - The GCP region where the Managed Instance Group resides. - Providing this parameter indicates the MIG is regional. Conflicts with `zone`. - -- `zone` `(string: "")` - The GCP zone where the Managed Instance Group resides. - Providing this parameter indicates the MIG is zonal. Conflicts with `region`. - -- `mig_name` `(string: )` - The name of the GCP Managed Instance Group - to interact with when performing scaling actions. - -- `datacenter` `(string: "")` - The Nomad client [datacenter][datacenter] identifier - used to group nodes into a pool of resource. Conflicts with `node_class`. - -- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] identifier - used to group nodes into a pool of resource. Conflicts with `datacenter`. - -- `node_drain_deadline` `(duration: "15m")` The Nomad [drain deadline][nomad_node_drain_deadline] - to use when performing node draining actions. **Please note that the default value - for this setting differs from Nomad's default of 1h.** - -- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to control if - system jobs should be stopped when performing node draining actions. - -- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad clients should - be [purged][nomad_node_purge] when performing scale in actions. - -- `node_selector_strategy` `(string: "least_busy")` The strategy to use when selecting - nodes for termination. Please see the [node selector strategy][node_selector_strategy] - documentation for more detailed information. - -[nomad_node_class]: /docs/configuration/client#node_class -[datacenter]: /docs/configuration#datacenter -[nomad_node_drain_deadline]: /api-docs/nodes#deadline -[nomad_scaling_stanza]: /docs/job-specification/scaling -[nomad_group_stanza]: /docs/job-specification/group#group-stanza -[nomad_job_stanza]: /docs/job-specification/job#job-stanza -[aws_region]: https://aws.amazon.com/about-aws/global-infrastructure/regions_az/ -[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 -[azure_virtual_machine_scale_sets]: https://docs.microsoft.com/en-us/azure/virtual-machine-scale-sets/overview -[vault_azure_backend]: https://www.vaultproject.io/docs/secrets/azure -[azure_resource_group]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group -[nomad_task_group_target]: /docs/autoscaling/plugins/target#nomad-task-group-target -[aws_asg_target]: /docs/autoscaling/plugins/target#aws-autoscaling-group-target -[azure_vmss_target]: /docs/autoscaling/plugins/target#azure-virtual-machine-scale-set-target -[vm_identity]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/ -[client_meta_tag_docs]: https://www.nomadproject.io/docs/configuration/client#meta -[client_meta_tag]: /docs/autoscaling/plugins/target#client-meta-tag -[azure_instance_metadata]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service -[das_task_target]: /docs/autoscaling/plugins/target#dynamic-application-sizing-nomad-task-target -[gcp_migs]: https://cloud.google.com/compute/docs/instance-groups/ -[vault_gcp_backend]: https://www.vaultproject.io/docs/secrets/gcp -[gcp_credentials]: https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application -[gcp_projects]: https://cloud.google.com/resource-manager/docs/creating-managing-projects -[gcp_mig_target]: /docs/autoscaling/plugins/target#google-cloud-platform-managed-instance-groups-target -[node_selector_strategy]: /docs/autoscaling/internals/node-selector-strategy diff --git a/website/content/docs/autoscaling/plugins/target/app-sizing-nomad.mdx b/website/content/docs/autoscaling/plugins/target/app-sizing-nomad.mdx new file mode 100644 index 000000000..73bfd4519 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/app-sizing-nomad.mdx @@ -0,0 +1,78 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Dynamic Application Sizing' +description: The "app-sizing-nomad" target plugin scales a task resource. +--- + +# Dynamic Application Sizing Nomad Task Target + + + 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`. + +[nomad_autoscaler_policy]: /docs/autoscaling/policy +[nomad_group_stanza]: /docs/job-specification/group +[nomad_job_stanza]: /docs/job-specification/job +[nomad_namespace_parameter]: /docs/job-specification/job#namespace +[nomad_recommendations_api]: /api-docs/recommendations +[nomad_region_parameter]: /docs/job-specification/job#region +[nomad_resource_stanza]: /docs/job-specification/resources +[nomad_scaling_stanza]: /docs/job-specification/scaling +[nomad_task_stanza]: /docs/job-specification/task diff --git a/website/content/docs/autoscaling/plugins/target/aws-asg.mdx b/website/content/docs/autoscaling/plugins/target/aws-asg.mdx new file mode 100644 index 000000000..2519cd85c --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/aws-asg.mdx @@ -0,0 +1,132 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: AWS ASG' +description: The "aws-asg" target plugin scales an Amazon Web Services Autoscaling Group. +--- + +# AWS AutoScaling Group Target + +The `aws-asg` target plugin allows for the scaling of the Nomad cluster clients +via manipulating [AWS AutoScaling Groups][aws_autoscaling]. + +## Agent Configuration Options + +To use the `aws-asg` target plugin, the agent configuration needs to be +populated with the appropriate target block. Authentication to the AWS API can +be supplied in a number of ways including EC2 instance roles. + +It is recommended, if possible to use the [Vault AWS Secrets +engine][vault_aws_backend] for supplying access credentials to the plugin. + +Credentials should be injected into the configuration via a template rather +than as environment variables. This ensures the credentials are passed only to +the plugin, rather than being available for all plugins and the agent process. + +The IAM policy required for the AWS ASG plugin to function properly is detailed +below. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "", + "Effect": "Allow", + "Action": [ + "autoscaling:UpdateAutoScalingGroup", + "autoscaling:DescribeScalingActivities", + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:CreateOrUpdateTags", + "autoscaling:TerminateInstanceInAutoScalingGroup" + ], + "Resource": "*" + } + ] +} +``` + +```hcl +target "aws-asg" { + driver = "aws-asg" + config = { + aws_region = "eu-west-3" + aws_access_key_id = "AKIAIOSFODNN7EXAMPLE" + aws_secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" + } +} +``` + +- `aws_region` `(string: "us-east-1")` - The [AWS region][aws_region] identifier + to connect to and where resources should be managed. + +- `aws_access_key_id` `(string: "")` - The AWS access key ID used to authenticate + with the AWS API. + +- `aws_secret_access_key` `(string: "")` - The AWS secret key ID used to authenticate + with the AWS API. + +- `aws_session_token` `(string: "")` - The AWS session token used to authenticate + with the AWS API. + +### Nomad ACL + +When using a Nomad cluster with ACLs enabled, the plugin will require an ACL +token which provides the following permissions: + +```hcl +node { + policy = "write" +} +``` + +## Policy Configuration Options + +```hcl +check "hashistack-allocated-cpu" { + # ... + target "aws-asg" { + aws_asg_name = "hashistack-client-asg" + node_class = "hashistack" + node_drain_deadline = "5m" + node_purge = "true" + } + # ... +} +``` + +- `aws_asg_name` `(string: )` - The name of the AWS AutoScaling Group to + interact with when performing scaling actions. + +- `datacenter` `(string: "")` - The Nomad client [datacenter][nomad_datacenter] + identifier used to group nodes into a pool of resource. Conflicts with + `node_class`. + +- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] + identifier used to group nodes into a pool of resource. Conflicts with + `datacenter`. + +- `node_drain_deadline` `(duration: "15m")` The Nomad [drain + deadline][nomad_node_drain_deadline] to use when performing node draining + actions. **Note that the default value for this setting differs from Nomad's + default of 1h.** + +- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to + control if system jobs should be stopped when performing node draining + actions. + +- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad + clients should be [purged][nomad_node_purge] when performing scale in + actions. + +- `node_selector_strategy` `(string: "least_busy")` The strategy to use when + selecting nodes for termination. Refer to the [node selector + strategy][node_selector_strategy] documentation for more information. + +[aws_autoscaling]: https://aws.amazon.com/autoscaling/ +[aws_region]: https://aws.amazon.com/about-aws/global-infrastructure/regions_az/ +[nomad_datacenter]: /docs/configuration#datacenter +[nomad_node_class]: /docs/configuration/client#node_class +[nomad_node_drain_deadline]: /api-docs/nodes#deadline +[nomad_node_purge]: /api-docs/nodes#purge-node +[node_selector_strategy]: /docs/autoscaling/internals/node-selector-strategy +[vault_aws_backend]: https://www.vaultproject.io/docs/secrets/aws diff --git a/website/content/docs/autoscaling/plugins/target/azure-vmss.mdx b/website/content/docs/autoscaling/plugins/target/azure-vmss.mdx new file mode 100644 index 000000000..e0118df4b --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/azure-vmss.mdx @@ -0,0 +1,147 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Azure VMSS' +description: The "azure-vmss" target plugin scales an Azure Virtual Machine Scale Set. +--- + +# Azure Virtual Machine Scale Set Target + +The `azure-vmss` target plugin allows for the scaling of the Nomad cluster +clients via manipulating [Azure Virtual Machine Scale +Sets][azure_virtual_machine_scale_sets]. + +~> The `azure-vmss` target plugin requires Azure fingerprinting, which was +added in Nomad 1.0. If you are running a previous version of Nomad you will to +set a [meta tag][client_meta_tag] in all of your nodes. + +## Agent Configuration Options + +To use the `azure-vmss` target plugin, the agent configuration needs to be +populated with the appropriate target block. Authentication to the Azure API +can be supplied in a number of ways. + +### Virtual Machine Identities + +When using [virtual machine identities][azure_vm_identity] you will need to +provide a user-managed identity with the `Contributor` role and set the +`subscription_id` in the Autoscaler configuration file: + +```hcl +target "azure-vmss" { + driver = "azure-vmss" + config = { + subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" + } +} +``` + +### Configuration file + +Credentials should be injected into the configuration via a template rather +than as environment variables. This ensures the credentials are passed only to +the plugin, rather than being available for all plugins and the agent process. +It is recommended, if possible to use the [Vault Azure Secrets +engine][vault_azure_backend] for supplying access credentials to the plugin. + +```hcl +target "azure-vmss" { + driver = "azure-vmss" + config = { + tenant_id = "02e99e69-91b0-4d0a-bd61-bf5c08fbfbab" + client_id = "34c276fa-2a74-4cf9-9fce-4e60642274cb" + secret_access_key = "ThisIrznTIS_~FAKEj4X93FTyAgilUC511" + subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" + } +} +``` + +- `tenant_id` `(string: "")` - The ID of the tenant to authenticate to. + +- `client_id` `(string: "")` - The app ID of the user-assigned identity in + Azure Active Directory. + +- `secret_access_key` `(string: "")` - The secret key ID used to authenticate + with the Azure API. + +- `subscription_id` `(string: "")` - The ID of the subscription to authenticate + to. + +### Nomad ACL + +When using a Nomad cluster with ACLs enabled, the plugin will require an ACL +token which provides the following permissions: + +```hcl +node { + policy = "write" +} +``` + +## Policy Configuration Options + +```hcl +check "clients-azure-vmss" { + # ... + target "azure-vmss" { + resource_group = "prod" + vm_scale_set = "hashistack-client-set" + node_class = "hashistack" + node_drain_deadline = "5m" + node_purge = "true" + } + # ... + +``` + +- `resource_group` `(string: )` - The name of the [Azure resource + group][azure_resource_group] within which the virtual machine scale set + resides. + +- `vm_scale_set` `(string: )` - The name of the Azure virtual machine + scale set to interact with when performing scaling actions. + +- `datacenter` `(string: "")` - The Nomad client [datacenter][nomad_datacenter] + identifier used to group nodes into a pool of resource. Conflicts with + `node_class`. + +- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] + identifier used to group nodes into a pool of resource. Conflicts with + `datacenter`. + +- `node_drain_deadline` `(duration: "15m")` The Nomad [drain + deadline][nomad_node_drain_deadline] to use when performing node draining + actions. **Note that the default value for this setting differs from Nomad's + default of 1h.** + +- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to + control if system jobs should be stopped when performing node draining + actions. + +- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad + clients should be [purged][nomad_node_purge] when performing scale in + actions. + +- `node_selector_strategy` `(string: "least_busy")` The strategy to use when + selecting nodes for termination. Refer to the [node selector + strategy][node_selector_strategy] documentation for more information. + +### Client meta tag + +The `azure-vmss` target plugin requires Nomad 1.0 for Azure fingerprinting. +Alternatively, you can set a [client meta tag][nomad_client_meta_tag] called +`unique.platform.azure.name` with the value being the Azure VMSS node name. +This can be retrieved programatically via the [Azure Instance Metadata +service][azure_instance_metadata]. + +[azure_instance_metadata]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service +[azure_resource_group]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group +[azure_virtual_machine_scale_sets]: https://docs.microsoft.com/en-us/azure/virtual-machine-scale-sets/overview +[azure_vm_identity]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/ +[client_meta_tag]: #client-meta-tag +[node_selector_strategy]: /docs/autoscaling/internals/node-selector-strategy +[nomad_datacenter]: /docs/configuration#datacenter +[nomad_client_meta_tag]: /docs/configuration/client#meta +[nomad_node_class]: /docs/configuration/client#node_class +[nomad_node_drain_deadline]: /api-docs/nodes#deadline +[nomad_node_purge]: /api-docs/nodes#purge-node +[vault_azure_backend]: https://www.vaultproject.io/docs/secrets/azure diff --git a/website/content/docs/autoscaling/plugins/target/gce-mig.mdx b/website/content/docs/autoscaling/plugins/target/gce-mig.mdx new file mode 100644 index 000000000..70abaf917 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/gce-mig.mdx @@ -0,0 +1,112 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: GCE MIG' +description: The "gcp-mig" target plugin scales a Google Cloud Engine Managed Instance Group. +--- + +# Google Cloud Engine Managed Instance Groups Target + +The `gce-mig` target plugin allows for the scaling of the Nomad cluster clients +via manipulating [Google Cloud Engine Managed Instance Groups][gce_migs]. The +plugin supports both regional and zonal groups. + +## Agent Configuration Options + +The plugin uses the official Google Cloud Golang SDK. This means it supports +the common ways of [providing credentials to Google Cloud][gcp_credentials]. + +It is recommended, if possible to use the [Vault GCP Secrets +engine][vault_gcp_backend] for supplying access credentials to the plugin. + +Credentials should be injected into the configuration via a template rather +than as environment variables. This ensures the credentials are passed only to +the plugin, rather than being available for all plugins and the agent process. + +```hcl +target "gce-mig" { + driver = "gce-mig" + config = { + credentials = "local/creds.json" + } +} +``` + +- `credentials` `(string: "")` - This is specified as the path to a Google Cloud + credentials file, typically for a service account. + +### Nomad ACL + +When using a Nomad cluster with ACLs enabled, the plugin will require an ACL token +which provides the following permissions: + +```hcl +node { + policy = "write" +} +``` + +## Policy Configuration Options + +```hcl +check "hashistack-allocated-cpu" { + # ... + target "gce-mig" { + project = "hashistack-demo" + region = "us-west1" + mig_name = "nomad-client-hashistack" + node_class = "hashistack" + node_drain_deadline = "5m" + node_purge = "true" + } + # ... +} +``` + +- `project` `(string: )` - The [Google Cloud Platform project + ID][gcp_projects] within which the managed instance group is running. + +- `region` `(string: "")` - The GCP region where the Managed Instance Group + resides. Providing this parameter indicates the MIG is regional. Conflicts + with `zone`. + +- `zone` `(string: "")` - The GCP zone where the Managed Instance Group + resides. Providing this parameter indicates the MIG is zonal. Conflicts with + `region`. + +- `mig_name` `(string: )` - The name of the GCE Managed Instance + Group to interact with when performing scaling actions. + +- `datacenter` `(string: "")` - The Nomad client [datacenter][nomad_datacenter] + identifier used to group nodes into a pool of resource. Conflicts with + `node_class`. + +- `node_class` `(string: "")` - The Nomad [client node class][nomad_node_class] + identifier used to group nodes into a pool of resource. Conflicts with + `datacenter`. + +- `node_drain_deadline` `(duration: "15m")` The Nomad [drain + deadline][nomad_node_drain_deadline] to use when performing node draining + actions. **Note that the default value for this setting differs from Nomad's + default of 1h.** + +- `node_drain_ignore_system_jobs` `(bool: "false")` A boolean flag used to + control if system jobs should be stopped when performing node draining + actions. + +- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad + clients should be [purged][nomad_node_purge] when performing scale in + actions. + +- `node_selector_strategy` `(string: "least_busy")` The strategy to use when + selecting nodes for termination. Refer to the [node selector + strategy][node_selector_strategy] documentation for more information. + +[gcp_credentials]: https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application +[gcp_projects]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[gce_migs]: https://cloud.google.com/compute/docs/instance-groups/ +[nomad_datacenter]: /docs/configuration#datacenter +[nomad_node_class]: /docs/configuration/client#node_class +[nomad_node_drain_deadline]: /api-docs/nodes#deadline +[nomad_node_purge]: /api-docs/nodes#purge-node +[node_selector_strategy]: /docs/autoscaling/internals/node-selector-strategy +[vault_gcp_backend]: https://www.vaultproject.io/docs/secrets/gcp diff --git a/website/content/docs/autoscaling/plugins/target/index.mdx b/website/content/docs/autoscaling/plugins/target/index.mdx new file mode 100644 index 000000000..a864bc24f --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/index.mdx @@ -0,0 +1,22 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Target' +description: Target plugins determine where the resource to be autoscaled is located. +--- + +# Target Plugins + +Target plugins determine where the resource to be autoscaled is located and +execute the scaling actions determined by the Autoscaler. + +The target can be a group of a Nomad job (in which case, the scaling type is +called horizontal application scaling), the number of Nomad clients (horizontal +cluster scaling), or the amount of resources assigned to a task of a Nomad job +(vertical application scaling). + +## Common Policy Configuration Options + +All target plugins support the following policy config parameters. + +- `dry-run` `(bool: false)` - If set to `true`, the target will not be scaled + and the proposed scaling action will only be logged. diff --git a/website/content/docs/autoscaling/plugins/target/nomad.mdx b/website/content/docs/autoscaling/plugins/target/nomad.mdx new file mode 100644 index 000000000..970b96327 --- /dev/null +++ b/website/content/docs/autoscaling/plugins/target/nomad.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: 'Autoscaling Plugins: Nomad' +description: The "nomad" target plugin scales a task group count. +--- + +# Nomad Task Group Target + +The Nomad task group target indicates the scalable resource is a Nomad job +running on a Nomad cluster. + +## Agent Configuration Options + +The Nomad target is automatically launched by the Nomad Autoscaler and so the +following setup is optional. + +```hcl +target "nomad" { + driver = "nomad" +} +``` + +## Policy Configuration Options + +If using the [Nomad job specification scaling stanza][nomad_scaling_stanza] to +configure the scaling policy, the following section can be omitted as Nomad will +populate them on job submission. + +```hcl +check "example-check" { + ... + target "nomad" { + Namespace = "default" + Job = "example" + Group = "cache" + } + ... +``` + +- `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]. + +[nomad_job_stanza]: /docs/job-specification/job#job-stanza +[nomad_group_stanza]: /docs/job-specification/group#group-stanza +[nomad_namespace_parameter]: /docs/job-specification/job#namespace +[nomad_scaling_stanza]: /docs/job-specification/scaling diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 644d4061c..6496e10ed 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1541,24 +1541,94 @@ }, { "title": "APM", - "path": "autoscaling/plugins/apm" - }, - { - "title": "Strategy", - "path": "autoscaling/plugins/strategy" - }, - { - "title": "Target", - "path": "autoscaling/plugins/target" - }, - { - "title": "Community", "routes": [ { "title": "Overview", - "path": "autoscaling/plugins/external" + "path": "autoscaling/plugins/apm" + }, + { + "title": "Datadog", + "path": "autoscaling/plugins/apm/datadog" + }, + { + "title": "Nomad API", + "path": "autoscaling/plugins/apm/nomad" + }, + { + "title": "Prometheus", + "path": "autoscaling/plugins/apm/prometheus" } ] + }, + { + "title": "Strategy", + "routes": [ + { + "title": "Overview", + "path": "autoscaling/plugins/strategy" + }, + { + "title": "Dynamic Application Sizing Average", + "path": "autoscaling/plugins/strategy/app-sizing-avg" + }, + { + "title": "Dynamic Application Sizing Max", + "path": "autoscaling/plugins/strategy/app-sizing-max" + }, + { + "title": "Dynamic Application Sizing Percentile", + "path": "autoscaling/plugins/strategy/app-sizing-percentile" + }, + { + "title": "Fixed Value", + "path": "autoscaling/plugins/strategy/fixed-value" + }, + { + "title": "Pass-Through", + "path": "autoscaling/plugins/strategy/pass-through" + }, + { + "title": "Target Value", + "path": "autoscaling/plugins/strategy/target-value" + }, + { + "title": "Threshold", + "path": "autoscaling/plugins/strategy/threshold" + } + ] + }, + { + "title": "Target", + "routes": [ + { + "title": "Overview", + "path": "autoscaling/plugins/target" + }, + { + "title": "Amazon Web Services Autoscaling Group", + "path": "autoscaling/plugins/target/aws-asg" + }, + { + "title": "Azure Virtual Machine Scale Set", + "path": "autoscaling/plugins/target/azure-vmss" + }, + { + "title": "Dynamic Application Sizing", + "path": "autoscaling/plugins/target/app-sizing-nomad" + }, + { + "title": "Google Cloud Engine Managed Instance Group", + "path": "autoscaling/plugins/target/gce-mig" + }, + { + "title": "Nomad Task Group", + "path": "autoscaling/plugins/target/nomad" + } + ] + }, + { + "title": "Community", + "path": "autoscaling/plugins/external" } ] },