zosbuilder/arch.md

Arch

Components

• EFI Image
  Minimal kernel providing a boot environment and network setup.

• Identity
  Manages node lifecycle: registration, updates, and identity.

• Supervisor
  Message router for registration procedures and authentication.

• Runners
  Workers listening on a job queue to execute tasks like VM CRUD operations.

• SALs (System Abstraction Layers)
  Wrappers around tools such as cloud-hypervisor, btrfs, and networking utilities.

• Coord (Coordinator)
  Workflow manager that selects the supervisor and ensures task completion.

• Ledger
  Centralized registration service for nodes, identity manager for users, and persistent store.

• Rhai Scripts
  Minimal scripts to execute high-level operations like VM deployment.

---

Node Lifecycle Flow

1. Build and push the EFI image to the bootstrap system.
2. Bootstrap flashes the image on a USB stick or generates an iPXE image.
3. Once booted and network is set up, the Identity Manager triggers.
4. Identity Manager contacts the centralized control plane (Ledger/Coord) for registration.
5. Node state (identity and keys) is saved, and uptime reports are sent periodically.

---

Deployment Flow

1. Client prepares a signed Rhai script with deployment specs, including loops and logic.
2. Script is sent to the Coord, which federates it to the relevant Supervisor, tracking execution and retries.
3. Supervisor verifies signatures, validates the script, and places jobs into the Redis queue.
4. Multiple Runners pick jobs from the queue and execute the corresponding SALs.

---

Features and Workloads

Networking

• Only Mycelium supported.
• No WireGuard/Yggdrasil/public overlays (public IPs only for gateway nodes).

Workloads

• Machines (VMs/containers)
• HeroDB
• Potential gateway support in the future (centralized Traefik)
• No QSFS/ZDB support

Filesystem

• Btrfs