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,
  "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 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 to take advantage of memory oversubscription. Node pools may set their own MemoryOversubscriptionEnabled 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.

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

{
  "SchedulerAlgorithm": "spread",
  "MemoryOversubscriptionEnabled": false,
  "RejectJobRegistration": false,
  "PauseEvalBroker": false,
  "PreemptionConfig": {
    "SystemSchedulerEnabled": true,
    "SysBatchSchedulerEnabled": false,
    "BatchSchedulerEnabled": false,
    "ServiceSchedulerEnabled": true
  },
  "NodeLimitForFeasibilityChecks": 100
}

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

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

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

• NodeLimitForFeasibilityChecks (int: 100) - Limits the number of feasible nodes to consider when scheduling a job that specifies spread and/or affinity. Defaults to 100 nodes if not set. Lower numbers result in better scheduler performance and more randomization of jobs across nodes. Higher numbers result in more deterministic application of spread and/or affinity. Refer to the scheduling performance content for more details on how this impacts scheduling performance.

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.