mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
2c3db7ee1d
During incident response, operators may find that automated processes elsewhere in the organization can be generating new workloads on Nomad clusters that are unable to handle the workload. This changeset adds a field to the `SchedulerConfiguration` API that causes all job registration calls to be rejected unless the request has a management ACL token.
166 lines
6.0 KiB
Plaintext
166 lines
6.0 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,
|
|
"RejectJobRegistration": false,
|
|
"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,
|
|
"RejectJobRegistration": 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.
|
|
|
|
- `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 proceses during incident response.
|
|
|
|
- `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
|