Skip to content

Design Notes

This section explains the architecture and implementation choices in the Barn 0.9.0 candidate.

Start with the product model, then follow the boundaries outward:

  1. Why Barn has no projects — one Inventory, one owner-scoped deployment, and no second source of truth.
  2. Why every node has two NICs — fixed identity for the lab, separate from management egress.
  3. Declarative does not mean destructive — per-node drift with explicit recreate and removal.
  4. A PID is not a virtual machine — QMP identity, process evidence, journals, and bounded recovery.
  5. repo.yaml is intent; catalog.json is evidence — a static image repository whose generated metadata is checked against the actual qcow2 bytes.

Use the documentation for current behavior and the status page for dated verification. These design records explain why those contracts exist; they do not turn a design, build, or local test into release evidence.

repo.yaml Is Intent; catalog.json Is Evidence ImagesSupply ChainCatalog
A PID Is Not a Virtual Machine QMPRecoverySafety
Declarative Does Not Mean Destructive LifecycleDriftSafety
Why Every Barn Node Has Two NICs NetworkingQEMUPigsty
Why Barn Has No Projects ArchitectureInventoryState

  • repo.yaml Is Intent; catalog.json Is Evidence

    In Design

    DesignImagesSupply ChainCatalog

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A static image repository sounds like a directory of qcow2 files plus a JSON index. The difficult part is deciding which …

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A static image repository sounds like a directory of qcow2 files plus a JSON index. The difficult part is deciding which …

  • A PID Is Not a Virtual Machine

    In Design

    DesignQMPRecoverySafety

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A pidfile answers one question: which integer did a process have when the file was written? It does not prove that the …

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A pidfile answers one question: which integer did a process have when the file was written? It does not prove that the …

  • Declarative Does Not Mean Destructive

    In Design

    DesignLifecycleDriftSafety

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. “Declarative” is often shortened to “make reality equal the file.” That is a useful slogan until the file is incomplete, …

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. “Declarative” is often shortened to “make reality equal the file.” That is a useful slogan until the file is incomplete, …

  • Why Every Barn Node Has Two NICs

    In Design

    DesignNetworkingQEMUPigsty

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A Pigsty Inventory names machines by stable addresses. PostgreSQL replication, etcd membership, HAProxy backends, VIPs, …

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. A Pigsty Inventory names machines by stable addresses. PostgreSQL replication, etcd membership, HAProxy backends, VIPs, …

  • Why Barn Has No Projects

    In Design

    DesignArchitectureInventoryState

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. Barn began with a familiar VM-manager abstraction: a working directory was a project, a hidden marker gave it identity, …

    Note This article describes the unreleased Barn 0.9.0 candidate. See Status for current validation and remaining release checks. Barn began with a familiar VM-manager abstraction: a working directory was a project, a hidden marker gave it identity, …

Last modified 2026-09-29