Skip to content

README.md

Latest commit

 

History

History
158 lines (112 loc) · 6.69 KB

README.md

File metadata and controls

158 lines (112 loc) · 6.69 KB
Raw

Schedune

Schedune is an alpha-stage control plane and node agent for explainable scheduling, launch validation, managed runtime lifecycle, restart recovery, and orphan visibility across heterogeneous ARM and x86 infrastructure.

Main Purpose: Schedune tells infrastructure teams which machine can safely run a workload, proves why, validates runtime readiness before launch, then tracks what happened afterward.

Who it is for: Platform and infrastructure teams operating or evaluating mixed ARM, x86, private-cloud, and edge fleets. It is not designed for solo app developers deploying a single application.

Example Scenario:

  • Fleet: Mixed machines (ARM servers, x86 servers, edge mini PCs).
  • Intent: Run a workload (e.g., payments service VM) requiring 4 vCPU, 8GB RAM, and KVM.
  • Evaluation: Schedune inspects the fleet. It selects arm-01 (healthy, KVM works) and explicitly rejects others like arm-02 (missing KVM), x86-02 (stale telemetry), and edge-01 (insufficient memory).
  • Validation: Before launch, it validates KVM, binaries, and safe socket paths.
  • Tracking: After launch, it tracks the PID, backend readiness, events, and recovery state.

Status: v0.1.0-alpha / Experimental (Single-node technical preview) Community: Join the Schedune Discord Control Plane: Go Agent: Rust Persistence: SQLite Supported Runtimes:

  • KVM/QEMU: Execute
  • Cloud Hypervisor: Execute or Validate
  • Firecracker: Validate / Dry-Run (Execution coming soon)

Unlike generic orchestrators or traditional hypervisors, Schedune is built specifically to help organizations exit expensive legacy virtualization, adopt ARM infrastructure safely, and manage mixed fleets with lower operational risk.

Schedune Architecture Diagram

Where Schedune is today (Alpha)

Currently, the lower-half control plane is working. This includes:

  • Typed node truth, intake, and projection
  • Eligibility explainability (proving why a node was rejected)
  • Launch validation and dry-runs
  • Initial runtime execution paths (KVM/QEMU, Cloud Hypervisor)
  • State, trace, and events tracking
  • Restart recovery and orphan process visibility
  • Fixture demos for testing on non-Linux hosts

ARM Compatibility Note: Today, the workload architecture and intent is supplied by the user or examples. Future value will come from image/container/import evidence, but this is not yet implemented.

Schedune is not yet capable of full workload compatibility discovery/import, live migration, High Availability (HA), full storage/networking, or guest-internal app health.

What Schedune does today

  • Node capability ingestion: Agent inspects and emits versioned node truth.
  • Workload eligibility explanation: Explains why workloads are rejected.
  • Backend-aware launch validation: Catches host-level and artifact-level blockers.
  • Runtime lifecycle management: Persistent states, append-only traces.
  • Restart recovery: Rehydrates active workloads after a crash, surfaces orphans.
  • Orphan visibility: Explicit orphan detection sweeping without destructive actions.

Quickstart

Get a single-node Schedune control plane and agent running in under 5 minutes.

1. Preflight Check

Check if your local host is ready for the evaluator:

make dev-preflight

2. Evaluator Demo (Linux)

If you are on a Linux host with KVM, run the end-to-end evaluator journey. This builds the components, starts the control plane, inspects your local node, ingests the truth, and evaluates a sample workload intent.

make demo

3. Evaluate from a MacBook / non-Linux host

On a MacBook M2 Air (or other non-Linux hosts), you can still test control-plane intake, scheduling explainability, launch validation against fixture truth, node APIs, and orphan API shape. Actual VM/microVM execution requires Linux with KVM and runtime binaries.

Run the fixture-backed evaluator demo to quickly verify the pipeline:

make demo-fixture-once

For an interactive session where you can explore the API manually afterwards, run:

make demo-fixture

3. Step-by-Step Examples

If you want to run it manually using the provided targets:

make dev-up                  # Start control plane in background
make example-intake          # Ingest your node capabilities
make example-schedule        # Run a scheduling explanation
make example-launch-validate # Validate a cloud-hypervisor launch
make example-launch-execute  # Execute a cloud-hypervisor launch
make example-orphans         # Check for orphaned processes
make dev-down                # Stop the control plane

4. Live Lab Demo

If you are on an x86_64 Linux host or nested-KVM x86_64 environment with KVM and QEMU, you can run the live lab demo which executes a KVM workload natively:

make demo-live-lab

For more information, see the Live Lab Demo documentation.

Repository Layout

  • schedune-control-plane/: The Go-based control plane, API, and orchestration logic.
  • schedune-agent/: The Rust-based node agent for inspection and capability emission.
  • docs/: Technical documentation and schemas.
  • examples/: Example launch specs, workload intents, and curl wrappers.
  • scripts/: Helper scripts for demo and preflight checks.

Design Principles

  • Agent emits truth; control plane projects truth. The agent observes; it does not orchestrate.
  • Eligibility before scoring. Workloads are explicitly rejected with exact reason codes.
  • Launch validation before execution. Fails fast on missing dependencies or permissions.
  • State, trace, and events separate. Predictable lifecycle tracking and append-only debugging.
  • Unknown is better than wrong. If Schedune cannot verify a capability, it assumes it is absent.
  • Orphan processes are surfaced, not guessed at or destroyed. Operators have visibility to resolve out-of-band state manually.

Current Limitations

Schedune explicitly does not support:

  • High Availability (HA) control plane
  • Auto-orphan adoption
  • Live migration
  • Advanced guest-service readiness (only hypervisor readiness is tracked)

Documentation

The full documentation is available in the docs/ directory and can be built locally using MkDocs:

pip install -r docs/requirements.txt
mkdocs serve

License

Copyright 2026 Technology Tailors. Licensed under the Apache License, Version 2.0.