162 lines
5.5 KiB
Plaintext
162 lines
5.5 KiB
Plaintext
---
|
|
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,
|
|
"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)` <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.
|
|
|
|
- `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.
|
|
|
|
| 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,
|
|
"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)` <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.
|
|
|
|
- `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
|
|
|
|
```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
|