---
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. Node pools may set
    their own [`SchedulerAlgorithm`][np_sched_algo] value that takes precedence
    over this global value.

  - `MemoryOversubscriptionEnabled` `(bool: false)` - 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. Node pools may set their own
    [`MemoryOversubscriptionEnabled`][np_mem_oversubs] value that takes
    precedence over this global value.

  - `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"`. This value may also be set per [node
  pool][np_sched_algo].

- `MemoryOversubscriptionEnabled` `(bool: false)` - 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. This value may also be set per
  [node pool][np_mem_oversubs].

- `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)` <sup>1.2</sup> - 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
[np_mem_oversubs]: /nomad/docs/other-specifications/node-pool#memory_oversubscription_enabled
[np_sched_algo]: /nomad/docs/other-specifications/node-pool#scheduler_algorithm
