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.
Sandboxmust be released viaPlacement::releaseonce the job finishes (success, failure, timeout, or cancellation) so the admission reservation and warm-pool slot are given back — seeSandboxPool::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
PodSandboxConfiga job’sresources:hints +runs_onlabel translate to for admission (#525 P2): cpu/memory becomelinux.resources,gpubecomes theANN_GPU_REQUESTannotation (the same vocabularyruntime::admission::derive_demandalready reads), and theruns_onlabel becomes theANN_GROUPannotation — a B′ group selector, validated against the verified Subject’s membership by the pool’sGroupSelectorValidatorat 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 (anIN_PROC_LABELSalias) or because no label was usefully provided (empty string).