docs: node pool specification (#17553)

website/content/docs/other-specifications/node-pool.mdx

@@ -0,0 +1,76 @@
+---
+layout: docs
+page_title: Nomad Node Pool Specification
+description: Learn about Nomad's Node Pool specification.
+---
+
+# Nomad Node Pool Specification
+
+Nomad node pools may be specified as HCL files and submitted by the [`nomad node
+pool apply`][pool-apply] CLI command.
+
+Unlike [Job specifications][jobspecs], Nomad node pool specifications do *not*
+support HCL2 features like functions.
+
+Example node pool specification generated by [`nomad node pool
+init`][pool-init]:
+
+```hcl
+node_pool "example" {
+
+  description = "Example node pool"
+
+  # meta is optional metadata on the node pool, defined as key-value pairs.
+  # The scheduler does not use node pool metadata as part of scheduling.
+  meta {
+    environment = "prod"
+    owner       = "sre"
+  }
+
+  # The scheduler configuration options specific to this node pool. This block
+  # supports a subset of the fields supported in the global scheduler
+  # configuration as described at:
+  # https://developer.hashicorp.com/nomad/docs/commands/operator/scheduler/set-config
+  #
+  # * scheduler_algorithm is the scheduling algorithm to use for the pool.
+  #   If not defined, the global cluster scheduling algorithm is used.
+  #
+  # Available only in Nomad Enterprise.
+
+  # scheduler_configuration {
+  #   scheduler_algorithm = "spread"
+  # }
+}
+```
+
+Example usage if the above is in a file named `pool.nomad.hcl`:
+
+```shell-session
+$ nomad node pool apply ./pool.nomad.hcl
+Successfully applied node pool "example"!
+```
+
+## Node Pool Specification Parameters
+
+- `description` `(string: <optional>)` - Sets a human readable description for
+  the node pool.
+
+- `meta` `(map[string]string: <optional>)` - Sets optional metadata on the node
+  pool, defined as key-value pairs. The scheduler does not use node pool metadat
+  as part of scheduling.
+
+- `scheduler_configuration` <code>([SchedulerConfig][sched-config]:
+  nil)</code> - Sets scheduler configuration options specific to the node
+  pool. If not defined, the global cluster scheduling algorithm is
+  used. Available only in Nomad Enterprise.
+
+### Scheduler Configuration Parameters
+
+- `scheduler_algorithm` `(string: <optional>)` - The [scheduler algorithm][]
+  used for this node pool. Must be one of `binpack` or `spread`.
+
+[pool-apply]: /nomad/docs/commands/node-pool/apply
+[jobspecs]: /nomad/docs/job-specification
+[pool-init]: /nomad/docs/commands/node-pool/init
+[sched-config]: #scheduler-configuration-parameters
+[scheduler algorithm]: /nomad/api-docs/operator/scheduler#scheduleralgorithm-1

website/data/docs-nav-data.json

@@ -1744,6 +1744,10 @@
         "title": "ACL Policy",
         "path": "other-specifications/acl-policy"
       },
+      {
+        "title": "Node Pool",
+        "path": "other-specifications/node-pool"
+      },
       {
         "title": "Variables",
         "path": "other-specifications/variables"