Merge pull request #10270 from hashicorp/f-docs-autoscaling-selector-strategy

docs: add autoscaling docs to detail node selector strategy feat.

website/content/docs/autoscaling/internals/node-selector-strategy.mdx

@@ -0,0 +1,47 @@
+---
+layout: docs
+page_title: Node Selector Strategy
+description: Learn about the Autoscaler's node selection strategies.
+---
+
+# Node Selector Strategy
+
+The node selector strategy is a mechanism the Nomad Autoscaler uses to identify
+nodes for termination when performing horizontal cluster scale-in actions. It
+is exposed as a target configuration option so that operators can modify its
+behaviour based on requirements.
+
+### `least_busy` Node Selector Strategy
+
+The `least_busy` strategy is the default node selector strategy used if the
+`node_selector_strategy` configuration option is omitted. When used, the Nomad
+Autoscaler will sort nodes based on their overall CPU and memory allocation;
+picking those with the lowest values. In the event a number of nodes have the
+same allocated percentage value, the selection will be random according to Golang's
+sort implementation.
+
+The `least_busy` strategy suits workloads that can tolerate migrations but
+allows you to minimise such events.
+
+### `empty` Node Selector Strategy
+
+The `empty` strategy will only consider nodes eligible for termination if they
+have zero non-terminal allocations. The terminal status of an allocation is
+determined using [these Nomad SDK allocation functions][nomad_api_terminal_alloc].
+The strategy will skip any node that does not meet this requirement. This can
+result in scaling actions terminating a smaller number of nodes than desired. In
+the event no nodes are found to be empty, the Nomad Autoscaler will decline to
+perform the scaling action.
+
+The `empty` strategy is ideal for batch workloads, ensuring allocations are not
+interrupted by scaling.
+
+### `newest_create_index` Node Selector Strategy
+
+The `newest_create_index` strategy is the simplest strategy and uses the order
+in which nodes are returned by the [Nomad SDK][nomad_api_node_stub_sort]. The
+strategy is ideal for workloads and environments which can handle migrations
+due to scaling. It is also the least computationally intensive selector strategy.
+
+[nomad_api_terminal_alloc]: https://github.com/hashicorp/nomad/blob/14568b3e002868fc5c83ee7d158a78394c1ea9c1/api/allocations.go#L422-L442
+[nomad_api_node_stub_sort]: https://github.com/hashicorp/nomad/blob/14568b3e002868fc5c83ee7d158a78394c1ea9c1/api/nodes.go#L797-L810

website/content/docs/autoscaling/plugins/target.mdx

@@ -227,6 +227,10 @@ check "hashistack-allocated-cpu" {
 - `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
@@ -334,6 +338,10 @@ check "clients-azure-vmss" {
 - `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.
@@ -420,6 +428,10 @@ check "hashistack-allocated-cpu" {
 - `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
 [nomad_node_drain_deadline]: /api-docs/nodes#deadline
 [nomad_scaling_stanza]: /docs/job-specification/scaling
@@ -451,3 +463,4 @@ check "hashistack-allocated-cpu" {
 [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

website/data/docs-nav-data.json

@@ -1520,6 +1520,10 @@
             "title": "Checks",
             "path": "autoscaling/internals/checks"
           },
+          {
+            "title": "Node Selector Strategy",
+            "path": "autoscaling/internals/node-selector-strategy"
+          },
           {
             "title": "Plugins",
             "routes": [