diff --git a/website/pages/api-docs/operator.mdx b/website/pages/api-docs/operator.mdx index bccd969a6..1ecec1afb 100644 --- a/website/pages/api-docs/operator.mdx +++ b/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"` -- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for various schedulers. -- `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. +- `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler + binpacks or spreads allocations on available nodes. Possible values are + `"binpack"` and `"spread"` + +- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for + various schedulers. + + - `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 \ No newline at end of file diff --git a/website/pages/docs/configuration/server.mdx b/website/pages/docs/configuration/server.mdx index 0e80ef691..aafc40275 100644 --- a/website/pages/docs/configuration/server.mdx +++ b/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 \ No newline at end of file diff --git a/website/pages/docs/faq.mdx b/website/pages/docs/faq.mdx index abc413741..f8e13bef2 100644 --- a/website/pages/docs/faq.mdx +++ b/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