github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/operator/scheduler.mdx

---
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](/api-docs#blocking-queries) and
[required ACLs](/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)` <sup>1.1 Beta</sup> - 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.

    - `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](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required     |
| ---------------- | ---------------- |
| `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
  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)` <sup>1.1 Beta</sup> - 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.

  - `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`]: /docs/configuration/server#default_scheduler_config