Skip to main content

Scheduler SDK reference

View Markdown

Scheduler SDK reference

Customer-hosted cloud features​

note

Some features are only available on customer-hosted clouds. Reach out to support@anyscale.com for info.

Scheduler SDK​

anyscale.scheduler.apply_config​

Apply a scheduler config (creates a new active version). Returns the new version number.

The previous active version becomes inactive but remains queryable via list_config_versions and get_config(version=N). Schema is validated locally before the API call; cross-reference checks (queue refs, flavor refs) happen on the server.

Arguments

  • config (SchedulerConfig | Dict[str, Any]): Scheduler config to apply. Either a SchedulerConfig dataclass or a dict matching the API schema.

Returns: int

Examples​

import anyscale
from anyscale.scheduler.models import SchedulerConfig

# Load from a YAML file (recommended).
config = SchedulerConfig.from_yaml("scheduler-config.yaml")
version = anyscale.scheduler.apply_config(config)
print(f"Applied scheduler config version {version}")

# Or pass a dict directly.
anyscale.scheduler.apply_config({
    "resource_flavors": [...],
    "resource_queues": [...],
    "scheduling_rules": [...],
})

anyscale.scheduler.get_config​

Get the active scheduler config (or a specific version).

Returns the version number, active flag, creator, created_at, and the full SchedulerConfig.

Arguments

  • version (int | None) = None: Specific version to fetch. Omit to fetch the active config.

Returns: SchedulerConfigVersion

Examples​

import anyscale

# Active config (default).
active = anyscale.scheduler.get_config()
print(active.version, active.config)

# A specific historical version.
v3 = anyscale.scheduler.get_config(version=3)

anyscale.scheduler.list_config_versions​

List scheduler config version history (newest first).

Returns metadata (version, created_at, creator_id) without the config blob. Use get_config(version=N) to fetch the full config for a specific version.

Arguments

  • max_items (int) = 10: Maximum number of versions to return. Defaults to 10.

Returns: List[SchedulerConfigVersionSummary]

Examples​

import anyscale

# Default: 10 most recent versions.
for summary in anyscale.scheduler.list_config_versions():
    print(summary.version, summary.created_at, summary.creator_id)

# Fetch any number; the SDK paginates internally.
recent = anyscale.scheduler.list_config_versions(max_items=200)

Scheduler models​

SchedulerConfig​

Top-level Global Resource Scheduler config.

A scheduler config is org-scoped. Apply to create a new active version; previous versions remain queryable.

Fields​

  • resource_flavors (List[ResourceFlavor] | None): Named flavors describing which instances satisfy each flavor (via match expressions) plus optional advanced launch overrides.
  • resource_queues (List[ResourceQueue] | None): Queues requests land in. Each carries optional preemption and per-flavor quotas.
  • scheduling_rules (List[SchedulingRule] | None): Rules routing incoming requests to a queue based on a structured label selector.

Python Methods​

def __init__(self, **fields) -> SchedulerConfig
    """Construct a model with the provided field values set."""

def options(self, **fields) -> SchedulerConfig
    """Return a copy of the model with the provided field values overwritten."""

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

resource_flavors:
  - name: spot
    selector:
      - key: market
        operator: in
        values: [spot]
resource_queues:
  - name: research
    preemption:
      within_resource_queue: lower_priority
    resource_groups:
      - covered_resources: [gpu]
        flavors:
          - name: spot
            resources:
              - name: gpu
                nominal_quota: 64
scheduling_rules:
  - resource_queue: research
    selector:
      - key: team
        operator: in
        values: [research]
    priority_policy:
      default: 50
      min: 0
      max: 100
      on_violation: reject

ResourceFlavor​

A named flavor with an optional match-expression selector and advanced launch overrides.

Fields​

  • name (str): Unique name for this resource flavor.
  • selector (List[MatchExpression] | None): Match expressions describing which instances satisfy this flavor.
  • advanced_instance_config (Dict[str, Any] | None): Cloud-provider-specific advanced launch overrides for instances of this flavor.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import ResourceFlavor, MatchExpression, Operator

flavor = ResourceFlavor(
    name="spot",
    selector=[
        MatchExpression(key="market", operator=Operator.IN, values=["spot"]),
    ],
)

MatchExpression​

A structured label-match used in scheduling-rule and flavor selectors.

Fields​

  • key (str): Label key to match against.
  • operator (Operator): Match operator: 'in', 'not_in', 'exists', or 'does_not_exist'.
  • values (List[str] | None): Values for 'in'/'not_in' (must be non-empty). Must be empty or omitted for 'exists'/'does_not_exist'.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import MatchExpression, Operator

expr = MatchExpression(key="team", operator=Operator.IN, values=["research", "ml"])

Operator​

Operator used in a match expression.

Values​

  • IN: Key's value is in the supplied values list.
  • NOT_IN: Key's value is not in the supplied values list.
  • EXISTS: Key is present on the request (values must be empty).
  • DOES_NOT_EXIST: Key is absent from the request (values must be empty).

ResourceQueue​

A queue requests are routed to. Carries optional preemption and per-flavor quotas.

Fields​

  • name (str): Unique name for this resource queue.
  • preemption (PreemptionPolicy | None): Preemption settings for this queue.
  • resource_groups (List[ResourceGroup] | None): Quota groups, one per set of covered resources, with per-flavor capacity.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import ResourceQueue

queue = ResourceQueue(name="research")

ResourceGroup​

A group of flavors that share the same set of covered resources.

Fields​

  • covered_resources (List[str]): Resources covered by this group (e.g. ['gpu'] or ['cpu', 'memory_gb']).
  • flavors (List[FlavorQuota]): Flavor-level quotas for the resources in covered_resources.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import ResourceGroup, FlavorQuota, ResourceQuotaSpec

group = ResourceGroup(
    covered_resources=["gpu"],
    flavors=[
        FlavorQuota(
            name="spot",
            resources=[ResourceQuotaSpec(name="gpu", nominal_quota=64)],
        ),
    ],
)

FlavorQuota​

Per-flavor quota specs within a resource group.

Fields​

  • name (str): Name of the resource flavor this quota applies to.
  • resources (List[ResourceQuotaSpec] | None): Per-resource quotas (e.g. one entry per covered resource). A covered resource omitted here (or an empty list) gets unlimited quota.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import FlavorQuota, ResourceQuotaSpec

flavor_quota = FlavorQuota(
    name="spot",
    resources=[ResourceQuotaSpec(name="gpu", nominal_quota=64)],
)

ResourceQuotaSpec​

Quota for a single resource (e.g. gpu, cpu) within a flavor.

Fields​

  • name (str): Resource name (e.g. 'gpu', 'cpu').
  • nominal_quota (float | None): Guaranteed capacity for this queue+flavor+resource (up to 3 decimal places). Omit for unlimited quota; an explicit 0 blocks it.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import ResourceQuotaSpec

quota = ResourceQuotaSpec(name="gpu", nominal_quota=64)

PreemptionPolicy​

Preemption settings for a resource queue.

Fields​

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import (
    PreemptionPolicy,
    PreemptionPolicyWithinResourceQueue,
)

policy = PreemptionPolicy(
    within_resource_queue=PreemptionPolicyWithinResourceQueue.LOWER_PRIORITY,
)

PreemptionPolicyWithinResourceQueue​

Preemption behavior for requests within the same resource queue.

Values​

  • NEVER: Never preempt requests within the same queue.
  • LOWER_PRIORITY: Preempt strictly lower-priority requests in the same queue.

SchedulingRule​

Routes incoming requests to a queue based on a structured label selector.

Fields​

  • resource_queue (str): Name of the queue requests matching this rule are routed to.
  • selector (List[MatchExpression] | None): Match expressions evaluated against request labels. Omit to match all requests not matched by an earlier rule.
  • priority_policy (PriorityPolicy | None): Priority bounds applied to requests matched by this rule.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import SchedulingRule, MatchExpression, Operator

rule = SchedulingRule(
    resource_queue="research",
    selector=[MatchExpression(key="team", operator=Operator.IN, values=["research"])],
)

PriorityPolicy​

Priority bounds applied to requests matched by a scheduling rule.

Fields​

  • default (int | None): Default priority assigned to matching requests.
  • min (int | None): Minimum allowed priority.
  • max (int | None): Maximum allowed priority.
  • on_violation (OnViolationAction | None): Action when a request's priority is outside [min, max]: 'reject' rejects, 'force_update' clamps.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

from anyscale.scheduler.models import PriorityPolicy, OnViolationAction

policy = PriorityPolicy(default=50, min=0, max=100, on_violation=OnViolationAction.REJECT)

OnViolationAction​

Action to take when a request priority is outside the policy's [min, max].

Values​

  • REJECT: Reject the request when its priority is outside [min, max].
  • FORCE_UPDATE: Clamp the priority to the nearest in-range value and continue.

SchedulerConfigVersion​

A specific version of a scheduler config (active or historical).

Fields​

  • version (int): Monotonic version number for this config.
  • is_active (bool): Whether this is the currently active config.
  • created_at (datetime): Timestamp at which this version was applied.
  • creator_id (str): User ID of the principal that applied this version.
  • config (SchedulerConfig): The full scheduler config for this version.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

import anyscale

version = anyscale.scheduler.get_config()
print(version.version, version.is_active, version.config)

SchedulerConfigVersionSummary​

Metadata-only summary of a scheduler config version (used by list).

Fields​

  • version (int): Monotonic version number.
  • created_at (datetime): Timestamp at which this version was applied.
  • creator_id (str): User ID of the principal that applied this version.

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

import anyscale

for v in anyscale.scheduler.list_config_versions():
    print(v.version, v.created_at, v.creator_id)