docs/ethos.md

Ref: Size: 2.8 KiB History
# eitri design ethos

*Something to fall back on when a design debate stalls.*

## North star

eitri is a **general-purpose cloud for quasi-cattle**—user-administered VMs with an on-demand lifecycle (throwaway → long-lived webserver).

> **The guest owns the guest; eitri owns the fleet.**

That line is the tie-breaker for almost everything.

## Principles

Each is tagged with a real fork it settled, so it stays concrete rather than aspirational.

1. **The guest/fleet boundary is the VM's edge.** Inside—kernel, packages, filesystem, in-VM config—is the user's; don't manage it. Outside—placement, lifecycle, access seam, quotas, identity—is eitri's; own it fully.
   *→ guests own their kernel (UEFI + guest GRUB, not pinned by us); cloud-init injection stays minimal.*

2. **When unsure, do what a real cloud does—and distrust anything the clouds abandoned.** EC2/GCE/Linode/DO already paid for these lessons.
   *→ UEFI + guest GRUB, not provider-pinned external kernels (which AWS→PV-GRUB, DigitalOcean, and Linode all migrated away from).*

3. **Composable, agnostic seams—BYO everything (CNI-style).** We care that an interface is satisfied, not what satisfies it.
   *→ BYO image = just a disk; network-provider seam; no hardcoded fabric, image, or kernel.*

4. **Design for the most demanding workload in the union, not the average.** The long-lived pet's needs dominate; serve it and the throwaway case is free.
   *→ "kernel security updates must take effect" (the webserver) drove UEFI over direct kernel boot.*

5. **Prefer the design that removes machinery.** Ballooning scope—extra wire fields, validation ladders, lifecycle plumbing—is a smell that you're on the wrong side of a boundary or fighting the ecosystem.
   *→ a firmware swap beat direct kernel boot + a wire contract + a validation ladder + kernel-as-control-plane-input.*

6. **Defer freely, foreclose never.** Ship the minimum; keep seams open so deferred features slot in without a rewrite.
   *→ multi-tenancy deferred but design-forward; direct kernel boot kept as a back-pocket fast-ephemeral profile.*

7. **Prove it on the stack; evidence over assertion.** Boot the VM, capture the serial.
   *→ the "modern images panic under CH firmware (EFI/Secure-Boot/TPM, CH #7356)" comment was flat wrong—only caught by reproducing it.*

## The "um and ahh" checklist

When a design debate stalls, walk this out loud. The first item that bites usually decides it.

1. Guest's business or fleet's? (guest → hands off)
2. What does EC2/GCE do here? (default to it; stop if it's something they abandoned)
3. Does this remove machinery or add it? (prefer removal)
4. Does it serve the long-lived pet? (design for that; throwaway comes free)
5. Are we deferring (fine) or foreclosing (stop)?
6. Have we booted it, or are we guessing?