From f9857747eac3bb8128ab3da12ff0e2b0c068457d Mon Sep 17 00:00:00 2001 From: James Rasell Date: Fri, 1 Jul 2022 11:43:16 +0100 Subject: [PATCH] docs: include new opertor scheduler CLI and pause eval API info. --- .changelog/13045.txt | 7 ++ .../content/api-docs/operator/scheduler.mdx | 56 +++++++++---- .../content/docs/commands/operator/index.mdx | 8 ++ .../operator/scheduler-get-config.mdx | 47 +++++++++++ .../operator/scheduler-set-config.mdx | 82 +++++++++++++++++++ website/content/docs/configuration/server.mdx | 7 +- website/data/docs-nav-data.json | 8 ++ 7 files changed, 197 insertions(+), 18 deletions(-) create mode 100644 .changelog/13045.txt create mode 100644 website/content/docs/commands/operator/scheduler-get-config.mdx create mode 100644 website/content/docs/commands/operator/scheduler-set-config.mdx diff --git a/.changelog/13045.txt b/.changelog/13045.txt new file mode 100644 index 000000000000..cb930bcf8676 --- /dev/null +++ b/.changelog/13045.txt @@ -0,0 +1,7 @@ +```release-note:improvement +cli: Added `scheduler get-config` and `scheduler set-config` commands to the operator CLI +``` + +```release-note:improvement +core: Added the ability to pause and un-pause the eval broker and blocked eval broker +``` diff --git a/website/content/api-docs/operator/scheduler.mdx b/website/content/api-docs/operator/scheduler.mdx index d007c5ce5891..3cf9d81e6a30 100644 --- a/website/content/api-docs/operator/scheduler.mdx +++ b/website/content/api-docs/operator/scheduler.mdx @@ -40,18 +40,20 @@ $ curl \ "Index": 5, "KnownLeader": true, "LastContact": 0, + "NextToken": "", "SchedulerConfig": { "CreateIndex": 5, + "MemoryOversubscriptionEnabled": false, "ModifyIndex": 5, - "SchedulerAlgorithm": "spread", - "MemoryOversubscriptionEnabled": true, - "RejectJobRegistration": false, + "PauseEvalBroker": false, "PreemptionConfig": { - "SystemSchedulerEnabled": true, - "SysBatchSchedulerEnabled": false, "BatchSchedulerEnabled": false, - "ServiceSchedulerEnabled": false - } + "ServiceSchedulerEnabled": false, + "SysBatchSchedulerEnabled": false, + "SystemSchedulerEnabled": true + }, + "RejectJobRegistration": false, + "SchedulerAlgorithm": "binpack" } } ``` @@ -64,9 +66,23 @@ $ curl \ - `SchedulerConfig` `(SchedulerConfig)` - The returned `SchedulerConfig` object has configuration settings mentioned below. - - `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler binpacks or spreads allocations on available nodes. + - `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler + binpacks or spreads allocations on available nodes. - - `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When `true`, tasks may exceed their reserved memory limit, if the client has excess memory capacity. Tasks must specify [`memory_max`](/docs/job-specification/resources#memory_max) to take advantage of memory oversubscription. + - `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When + `true`, tasks may exceed their reserved memory limit, if the client has excess + memory capacity. Tasks must specify [`memory_max`](/docs/job-specification/resources#memory_max) + to take advantage of memory oversubscription. + + - `RejectJobRegistration` `(bool: false)` - When `true`, the server will return + permission denied errors for job registration, job dispatch, and job scale APIs, + unless the ACL token for the request is a management token. If ACLs are disabled, + no user will be able to register jobs. This allows operators to shed load from + automated processes during incident response. + + - `PauseEvalBroker` `(bool: false)` - When set to `true`, the eval broker which + usually runs on the leader will be disabled. This will prevent the scheduler + workers from receiving new work. - `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for various schedulers. @@ -120,6 +136,7 @@ server state is authoritative. "SchedulerAlgorithm": "spread", "MemoryOversubscriptionEnabled": false, "RejectJobRegistration": false, + "PauseEvalBroker": false, "PreemptionConfig": { "SystemSchedulerEnabled": true, "SysBatchSchedulerEnabled": false, @@ -133,9 +150,20 @@ server state is authoritative. binpacks or spreads allocations on available nodes. Possible values are `"binpack"` and `"spread"` -- `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When `true`, tasks may exceed their reserved memory limit, if the client has excess memory capacity. Tasks must specify [`memory_max`](/docs/job-specification/resources#memory_max) to take advantage of memory oversubscription. +- `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When + `true`, tasks may exceed their reserved memory limit, if the client has excess + memory capacity. Tasks must specify [`memory_max`](/docs/job-specification/resources#memory_max) + to take advantage of memory oversubscription. -- `RejectJobRegistration` `(bool: false)` - When `true`, the server will return permission denied errors for job registration, job dispatch, and job scale APIs, unless the ACL token for the request is a management token. If ACLs are disabled, no user will be able to register jobs. This allows operators to shed load from automated proceses during incident response. +- `RejectJobRegistration` `(bool: false)` - When `true`, the server will return + permission denied errors for job registration, job dispatch, and job scale APIs, + unless the ACL token for the request is a management token. If ACLs are disabled, + no user will be able to register jobs. This allows operators to shed load from + automated processes during incident response. + +- `PauseEvalBroker` `(bool: false)` - When set to `true`, the eval broker which + usually runs on the leader will be disabled. This will prevent the scheduler + workers from receiving new work. - `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for various schedulers. @@ -143,9 +171,9 @@ server state is authoritative. - `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. - - - `SysBatchSchedulerEnabled` `(bool: false)` 1.2 - Specifies - whether preemption for system batch jobs is enabled. Note that if this is + + - `SysBatchSchedulerEnabled` `(bool: false)` 1.2 - Specifies + whether preemption for system batch jobs is enabled. Note that if this is set to true, then system batch jobs can preempt any other jobs. - `BatchSchedulerEnabled` `(bool: false)` - Specifies diff --git a/website/content/docs/commands/operator/index.mdx b/website/content/docs/commands/operator/index.mdx index c800a9643534..21043b3063da 100644 --- a/website/content/docs/commands/operator/index.mdx +++ b/website/content/docs/commands/operator/index.mdx @@ -42,6 +42,12 @@ The following subcommands are available: - [`operator raft remove-peer`][remove] - Remove a Nomad server from the Raft configuration +- [`operator scheduler get-config`][scheduler-get-config] - Display the current + scheduler configuration + +- [`operator scheduler set-config`][scheduler-set-config] - Modify the scheduler + configuration + - [`operator snapshot agent`][snapshot-agent] - Inspects a snapshot of the Nomad server state - [`operator snapshot save`][snapshot-save] - Saves a snapshot of the Nomad server state @@ -63,3 +69,5 @@ The following subcommands are available: [snapshot-restore]: /docs/commands/operator/snapshot-restore 'Snapshot Restore command' [snapshot-inspect]: /docs/commands/operator/snapshot-inspect 'Snapshot Inspect command' [snapshot-agent]: /docs/commands/operator/snapshot-agent 'Snapshot Agent command' +[scheduler-get-config]: /docs/commands/operator/scheduler-get-config 'Scheduler Get Config command' +[scheduler-set-config]: /docs/commands/operator/scheduler-set-config 'Scheduler Set Config command' diff --git a/website/content/docs/commands/operator/scheduler-get-config.mdx b/website/content/docs/commands/operator/scheduler-get-config.mdx new file mode 100644 index 000000000000..01a5d20499d3 --- /dev/null +++ b/website/content/docs/commands/operator/scheduler-get-config.mdx @@ -0,0 +1,47 @@ +--- +layout: docs +page_title: 'Commands: operator scheduler get-config' +description: | + Display the current scheduler configuration. +--- + +# Command: operator scheduler get-config + +The scheduler operator get-config command is used to view the current scheduler +configuration. + +## Usage + +```plaintext +nomad operator scheduler get-config [options] +``` + +If ACLs are enabled, this command requires a token with the `operator:read` +capability. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Get Config Options + +- `-json`: Output the scheduler config in its JSON format. + +- `-t`: Format and display the scheduler config using a Go template. + +## Examples + +Display the current scheduler configuration: + +```shell-session +$ nomad operator scheduler get-config +Scheduler Algorithm = binpack +Memory Oversubscription = false +Reject Job Registration = false +Pause Eval Broker = false +Preemption System Scheduler = true +Preemption Service Scheduler = false +Preemption Batch Scheduler = false +Preemption SysBatch Scheduler = false +Modify Index = 5 +``` diff --git a/website/content/docs/commands/operator/scheduler-set-config.mdx b/website/content/docs/commands/operator/scheduler-set-config.mdx new file mode 100644 index 000000000000..74b7f81750ce --- /dev/null +++ b/website/content/docs/commands/operator/scheduler-set-config.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: 'Commands: operator scheduler set-config' +description: | + Modify the scheduler configuration. +--- + +# Command: operator scheduler set-config + +The scheduler operator set-config command is used to modify the scheduler +configuration. + +## Usage + +```plaintext +nomad operator scheduler set-config [options] +``` + +If ACLs are enabled, this command requires a token with the `operator:write` +capability. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Set Config Options + +- `-check-index` - If set, the scheduler config is only updated if the passed + modify index matches the current server side version. If a non-zero value is + passed, it ensures that the scheduler config is being updated from a known + state. + +- `-scheduler-algorithm` - Specifies whether scheduler binpacks or spreads + allocations on available nodes. Must be one of `["binpack"|"spread"]`. + +- `-memory-oversubscription` - When true, tasks may exceed their reserved memory + limit, if the client has excess memory capacity. Tasks must specify [`memory_max`] + to take advantage of memory oversubscription. Must be one of `[true|false]`. + +- `-reject-job-registration` - When true, the server will return permission denied + errors for job registration, job dispatch, and job scale APIs, unless the ACL + token for the request is a management token. If ACLs are disabled, no user + will be able to register jobs. This allows operators to shed load from automated + processes during incident response. Must be one of `[true|false]`. + +- `-pause-eval-broker` - When set to true, the eval broker which usually runs on + the leader will be disabled. This will prevent the scheduler workers from + receiving new work. Must be one of `[true|false]`. + +- `-preempt-batch-scheduler` - Specifies whether preemption for batch jobs + is enabled. Note that if this is set to true, then batch jobs can preempt any + other jobs. Must be one of `[true|false]`. + +- `-preempt-service-scheduler` - Specifies whether preemption for service jobs + is enabled. Note that if this is set to true, then service jobs can preempt any + other jobs. Must be one of `[true|false]`. + +- `-preempt-sysbatch-scheduler` - Specifies whether preemption for system batch + jobs is enabled. Note that if this is set to true, then system batch jobs can + preempt any other jobs. Must be one of `[true|false]`. + +- `-preempt-system-scheduler` - Specifies whether preemption for system jobs + is enabled. Note that if this is set to true, then system jobs can preempt any + other jobs. Must be one of `[true|false]`. + +## Examples + +Modify the scheduler algorithm to spread: + +```shell-session +$ nomad operator scheduler set-config -scheduler-algorithm=spread +Scheduler configuration updated! +``` + +Modify the scheduler algorithm to spread using the check index flag: + +```shell-session +$ nomad operator scheduler set-config -scheduler-algorithm=spread -check-index=5 +Scheduler configuration updated! +``` + +[`memory_max`]: /docs/job-specification/resources#memory_max diff --git a/website/content/docs/configuration/server.mdx b/website/content/docs/configuration/server.mdx index 7872913a0640..d6f08c21851f 100644 --- a/website/content/docs/configuration/server.mdx +++ b/website/content/docs/configuration/server.mdx @@ -310,11 +310,10 @@ job-type schedulers. ```hcl server { default_scheduler_config { - scheduler_algorithm = "spread" - + scheduler_algorithm = "spread" memory_oversubscription_enabled = true - - reject_job_registration = false + reject_job_registration = false + pause_eval_broker = false # New in Nomad 1.3.2 preemption_config { batch_scheduler_enabled = true diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1d01c67875ce..eb549a664c09 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -585,6 +585,14 @@ "title": "raft state", "path": "commands/operator/raft-state" }, + { + "title": "scheduler get-config", + "path": "commands/operator/scheduler-get-config" + }, + { + "title": "scheduler set-config", + "path": "commands/operator/scheduler-set-config" + }, { "title": "snapshot agent", "path": "commands/operator/snapshot-agent"