--- layout: api page_title: Scheduler - Operator - HTTP API description: |- The /operator/scheduler endpoints provide tools for management of Nomad server scheduler settings. --- # Scheduler Operator HTTP API The `/operator/scheduler` endpoints provide tools for management of Nomad server scheduler settings. ## Read Scheduler Configuration This endpoint retrieves the latest Scheduler configuration. More options may be added in the future. | Method | Path | Produces | | ------ | -------------------------------------- | ------------------ | | `GET` | `/v1/operator/scheduler/configuration` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | --------------- | | `NO` | `operator:read` | ### Sample Request ```shell-session $ curl \ https://localhost:4646/v1/operator/scheduler/configuration ``` ### Sample Response ```json { "Index": 5, "KnownLeader": true, "LastContact": 0, "NextToken": "", "SchedulerConfig": { "CreateIndex": 5, "MemoryOversubscriptionEnabled": false, "ModifyIndex": 5, "PauseEvalBroker": false, "PreemptionConfig": { "BatchSchedulerEnabled": false, "ServiceSchedulerEnabled": false, "SysBatchSchedulerEnabled": false, "SystemSchedulerEnabled": true }, "RejectJobRegistration": false, "SchedulerAlgorithm": "binpack" } } ``` #### Field Reference - `Index` `(int)` - The `Index` value is the Raft index corresponding to this configuration. - `SchedulerConfig` `(SchedulerConfig)` - The returned `SchedulerConfig` object has configuration settings mentioned below. - `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`](/nomad/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. - `SystemSchedulerEnabled` `(bool: true)` - Specifies whether preemption for system jobs is enabled. Note that this defaults to true. - `SysBatchSchedulerEnabled` `(bool: false)` - Specifies whether preemption for system batch jobs is enabled. Note that this defaults to false. - `BatchSchedulerEnabled` `(bool: false)` - Specifies whether preemption for batch jobs is enabled. Note that this defaults to false and must be explicitly enabled. - `ServiceSchedulerEnabled` `(bool: false)` - Specifies whether preemption for service jobs is enabled. Note that this defaults to false and must be explicitly enabled. - `CreateIndex` - The Raft index at which the config was created. - `ModifyIndex` - The Raft index at which the config was modified. ## Update Scheduler Configuration This endpoint updates the scheduler configuration of the cluster. | Method | Path | Produces | | ------------- | -------------------------------------- | ------------------ | | `PUT`, `POST` | `/v1/operator/scheduler/configuration` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ---------------- | | `NO` | `operator:write` | ### Bootstrap Configuration Element The [`default_scheduler_config`][] attribute of the server block 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 only happen if the given index matches the `ModifyIndex` of the configuration at the time of writing. ### Sample Payload ```json { "SchedulerAlgorithm": "spread", "MemoryOversubscriptionEnabled": false, "RejectJobRegistration": false, "PauseEvalBroker": false, "PreemptionConfig": { "SystemSchedulerEnabled": true, "SysBatchSchedulerEnabled": false, "BatchSchedulerEnabled": false, "ServiceSchedulerEnabled": true } } ``` - `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler 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`](/nomad/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. - `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 set to true, then system batch jobs can preempt any other jobs. - `BatchSchedulerEnabled` `(bool: false)` - 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)` - 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`]: /nomad/docs/configuration/server#default_scheduler_config