Skip to main content

Module scheduler

Module scheduler 

Source
Expand description

Job → scheduled workload placement (#527).

Maps a job’s runs_on: label + resources: hints onto a placement decision and, for jobs that request isolation, acquires/releases a real sandbox reservation through the #525 P2 admission engine (SandboxPool::acquire) instead of the pre-#527 fire-and-forget tokio::spawn that ignored both.

§🔒 Mapping convention (ratified: B′ group semantics, #921 decision 5)

runs_on: <label> is matched, case-insensitively, against a small reserved alias set (IN_PROC_LABELS) meaning “no isolation — run in-process” (today’s VFS/Tcl execution path, unchanged). Any other label routes the job onto the JobScheduler’s configured SandboxPool and is recorded as the hyprstream_workers::runtime::ANN_GROUP annotation.

Under the ratified B′ semantics that annotation is a capacity-partition selector, never an authoritative quota/trust/billing key: admission (runtime::admission) resolves it against the verified Subject’s bidirectional-consent placement-group membership via the pool’s GroupSelectorValidator — a workflow naming a group its Subject is not a member of is rejected at admission, not silently accepted. The production default validator (DenyUnknownGroupValidator) fail-closes on every non-empty selector until a membership source (PlacementIndex::is_member) is wired, so an isolated runs_on: label is deny-by-default today. Validated labels partition node-local capacity via AdmissionConfig::max_per_group (fairness/organization only — authoritative quota arrives via the ledger path, #922/#925). This module adds no group accounting of its own: the label’s only consumer is the ANN_GROUP annotation read back by admission::derive_group_selector inside SandboxPool::acquire.

This is a label → group mapping, not a label → backend mapping: one JobScheduler wraps exactly one pre-resolved SandboxPool (bound to one crate::runtime::SandboxBackend at construction — see pool.rs’s own documented invariant that a pool never re-selects its backend per-request). runs_on: kata therefore does NOT pick a different backend than runs_on: nspawn within a single scheduler; both go to this scheduler’s one backend, merely tagged with a different admission group. Routing different labels to genuinely different backends would mean a router over multiple backend-specific pools — the same architectural change pool.rs already flags as a follow-up, not something this ticket re-derives. Flagged here explicitly for reviewer sign-off, per the issue’s disclosure ask.

§What “runs in a sandbox” means today (also flagged)

Placement acquires a real sandbox reservation — admission is checked, the backend’s start() actually runs (a real Kata VM boots when the pool is Kata-backed) — closing the #520 “no isolation” gap structurally: a job that requests isolation now really holds a sandbox for its duration. Step content execution (the uses:/run: bodies) still runs through the existing VFS /bin/ ctl + TclShell bridge on the host, not inside the guest’s own namespace — routing individual step exec into the guest (via kata_agent::ExecProcess, nspawn, etc.) needs the streaming/fd plane exec_mount.rs itself documents as not yet built. That is a materially larger follow-up, not attempted here.

Structs§

JobScheduler
Routes workflow jobs through the #525 P2 scheduler.

Enums§

Placement
A job’s resolved placement. Sandbox must be released via Placement::release once the job finishes (success, failure, timeout, or cancellation) so the admission reservation and warm-pool slot are given back — see SandboxPool::release’s own reservation-rollback discipline.

Constants§

IN_PROC_LABELS
runs_on: labels (case-insensitive) meaning “no isolation — run in-process” via the existing VFS/Tcl execution path. Anything else is treated as a request for this scheduler’s sandbox (see module docs).

Functions§

job_pod_sandbox_config
Build the PodSandboxConfig a job’s resources: hints + runs_on label translate to for admission (#525 P2): cpu/memory become linux.resources, gpu becomes the ANN_GPU_REQUEST annotation (the same vocabulary runtime::admission::derive_demand already reads), and the runs_on label becomes the ANN_GROUP annotation — a B′ group selector, validated against the verified Subject’s membership by the pool’s GroupSelectorValidator at admission (see module docs).
primary_label
The label that drives a job’s placement decision.
wants_in_proc
True when runs_on’s primary label requests in-process (no sandbox) execution — either explicitly (an IN_PROC_LABELS alias) or because no label was usefully provided (empty string).