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.

The table below shows this endpoint's support for blocking queries and required ACLs.

Sample Request

$ curl \
    https://localhost:4646/v1/operator/scheduler/configuration

Sample Response

{
  "Index": 5,
  "KnownLeader": true,
  "LastContact": 0,
  "SchedulerConfig": {
    "CreateIndex": 5,
    "ModifyIndex": 5,
    "SchedulerAlgorithm": "spread",
    "MemoryOversubscriptionEnabled": true,
    "PreemptionConfig": {
      "SystemSchedulerEnabled": true,
      "BatchSchedulerEnabled": false,
      "ServiceSchedulerEnabled": false
    }
  }
}

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 to take advantage of memory oversubscription.

  • 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.

    • 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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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

{
  "SchedulerAlgorithm": "spread",
  "MemoryOversubscriptionEnabled": false,
  "PreemptionConfig": {
    "SystemSchedulerEnabled": true,
    "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 to take advantage of memory oversubscription.

• 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) - 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

{
  "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.