Merge pull request #7994 from shantanugadgil/patch-3

update docs to mention spread algorithm

website/pages/api-docs/operator.mdx

@@ -411,6 +411,12 @@ The table below shows this endpoint's support for
 | ---------------- | ---------------- |
 | `NO`             | `operator:write` |
 
+### Bootstrap Configuration Element
+
+The [`default_scheduler_config`][] attribute of the server stanza will provide a
+starting value for this configuration. Once bootstrapped, the value in the
+server state is authoritative.
+
 ### Parameters
 
 - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will
@@ -430,11 +436,38 @@ The table below shows this endpoint's support for
 }
 ```
 
-- `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler binpacks or spreads allocations on available nodes. Possible values are `"binpack"` and `"spread"`
+- `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler
-- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for various schedulers.
+  binpacks or spreads allocations on available nodes.  Possible values are
-- `SystemSchedulerEnabled` `(bool: true)` - Specifies whether preemption for system jobs is enabled. Note that
+  `"binpack"` and `"spread"`
-  if this is set to true, then system jobs can preempt any other jobs.
+
-- `BatchSchedulerEnabled` `(bool: false)` (Enterprise Only) - Specifies whether preemption for batch jobs is enabled. Note that
+- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for
-  if this is set to true, then batch jobs can preempt any other jobs.
+  various schedulers.
-- `ServiceSchedulerEnabled` `(bool: false)` (Enterprise Only) - Specifies whether preemption for service jobs is enabled. Note that
+
-  if this is set to true, then service jobs can preempt any other jobs.
+  - `SystemSchedulerEnabled` `(bool: true)` - Specifies whether preemption for
+    system jobs is enabled. Note that if this is set to true, then system jobs
+    can preempt any other jobs.
+
+  - `BatchSchedulerEnabled` `(bool: false)` (Enterprise Only) - Specifies
+    whether preemption for batch jobs is enabled. Note that if this is set to
+    true, then batch jobs can preempt any other jobs.
+
+  - `ServiceSchedulerEnabled` `(bool: false)` (Enterprise Only) - Specifies
+    whether preemption for service jobs is enabled. Note that if this is set to
+    true, then service jobs can preempt any other jobs.
+
+### Sample Response
+
+```json
+{
+  "Updated": false,
+  "Index": 15
+}
+```
+
+- `Updated` - Indicates that the configuration was updated when a `cas` value is
+  provided. For non-CAS requests, this field will be false even though the
+  update is applied.
+
+- `Index` - Current Raft index when the request was received.
+
+[`default_scheduler_config`]: /docs/configuration/server#default_scheduler_config

website/pages/docs/configuration/server.mdx

@@ -239,14 +239,29 @@ server {
 }
 ```
 
-### Configuring Scheduler Config
+### Bootstrapping with a Custom Scheduler Config ((#configuring-scheduler-config))
 
-This example shows enabling preemption for all schedulers.
+While [bootstrapping a cluster], you can use the `default_scheduler_config` stanza
+to prime the cluster with a [`SchedulerConfig`][update-scheduler-config]. The
+scheduler configuration determines which scheduling algorithm is configured—
+spread scheduling or binpacking—and which job types are eligible for preemption.
+
+~> **Warning:** Once the cluster is bootstrapped, you must configure this using
+   the [update scheduler configuration][update-scheduler-config] API. This
+   option is only consulted during bootstrap.
+
+The structure matches the [Update Scheduler Config][update-scheduler-config] API
+endpoint, which you should consult for canonical documentation. However, the
+attributes names must be adapted to HCL syntax by using snake case
+representations rather than camel case.
+
+This example shows configuring spread scheduling and enabling preemption for all
+job-type schedulers.
 
 ```hcl
 server {
   default_scheduler_config {
-    scheduler_algorithm = "binpack"
+    scheduler_algorithm = "spread"
 
     preemption_config {
       batch_scheduler_enabled   = true
@@ -257,14 +272,7 @@ server {
 }
 ```
 
-The structure matches the [Update Scheduler Config][update-scheduler-config] endpoint,
-but adopted to hcl syntax (namely using snake case rather than camel case).
-
-Nomad servers check their `default_scheduler_config` only during cluster
-bootstrap. During upgrades, if a previously bootstrapped cluster already set
-scheduler configuration via the [Update Scheduler Config][update-scheduler-config]
-endpoint, that is always preferred.
-
 [encryption]: https://learn.hashicorp.com/nomad/transport-security/gossip-encryption 'Nomad Encryption Overview'
 [server-join]: /docs/configuration/server_join 'Server Join'
 [update-scheduler-config]: /api-docs/operator#update-scheduler-configuration 'Scheduler Config'
+[bootstrapping a cluster]: /docs/faq#bootstrapping

website/pages/docs/faq.mdx

@@ -37,6 +37,29 @@ Consul on the other hand does not have this two-tier approach to servers and
 agents and instead [relies on federation to create larger logical
 clusters][consul_fed].
 
+## Q: What is "bootstrapping" a Nomad cluster? ((#bootstrapping))
+
+Bootstrapping is the process when a Nomad cluster elects its first leader
+and writes the initial cluster state to that leader's state store. Bootstrapping
+will not occur until at least a given number of servers, defined by
+[`bootstrap_expect`], have connected to each other. Once this process has
+completed, the cluster is said to be bootstrapped and is ready to use.
+
+Certain configuration options are only used to influence the creation of the
+initial cluster state during bootstrapping and are not consulted again so long
+as the state data remains intact. These typically are values that must be
+consistent across server members. For example, the [`default_scheduler_config`]
+option allows an operator to set the SchedulerConfig to non-default values
+during this bootstrap process rather than requiring an immediate call to the API
+once the cluster is up and running.
+
+If the state is completely destroyed, whether intentionally or accidentally, on
+all of the Nomad servers in the same outage, the cluster will re-bootstrap based
+on the Nomad defaults and any configuration present that impacts the bootstrap
+process.
+
 [consul_dc]: https://www.consul.io/docs/agent/options.html#_datacenter
 [consul_fed]: https://www.consul.io/docs/guides/datacenters.html
 [nomad_region]: /docs/configuration#datacenter
+[`bootstrap_expect`]: /docs/configuration/server#bootstrap_expect
+[`default_scheduler_config`]: /docs/configuration/server#default_scheduler_config