Jean-Gabriel Gill-Couture
56602b505c
All checks were successful
Run Check Script / check (pull_request) Successful in 2m35s
Operator restart + aggregator recovery (v0.3 plan Ch2). The aggregator already cold-rebuilds from NATS KV + CR watches; this makes recovery observable, closes an orphan gap, and pins each failure shape with a regression test. - OperatorLiveness: a shared in-process latch (Recovering → Converged) the aggregator sets once all three cold-start sources replay (Deployment/Device watcher InitDone, device-state KV seen_current; empty-bucket short-circuit). The in-process dashboard reads it and shows a self-clearing banner via an HTMX self-poll (/__recovery), so the customer sees progress, not a blank. - gc_orphaned_desired_state: at convergence, purge desired-state whose Deployment CR no longer exists (force-deleted while the operator was down, finalizer bypassed). Belt-and-suspenders with the controller finalizer. - run() now owns its watchers in a JoinSet, so cancelling the aggregator aborts its children — no orphan tasks outliving a restart (matters for the restart-simulation tests and clean process teardown). Also made run() Send (hoisted a .await out of a tracing macro) so it can be spawned. - docs/fleet-operator-recovery-scenarios.md enumerates the failure shapes and maps each to its test. - harmony-fleet-e2e/tests/operator_recovery.rs: regression test per scenario (cold restart converges from KV; orphan GC; two operators write identical bytes; chaos kill under write load converges <30s) + AdminKv::put_device_state. Writes stay idempotent + byte-deterministic, so two operators racing agree without leader election (operator HA = D3, deferred).
Harmony Documentation Hub
Welcome to the Harmony documentation. This is the main entry point for learning everything from core concepts to building your own Score, Topologies, and Capabilities.
1. Getting Started
If you're new to Harmony, start here:
- Getting Started Guide: A step-by-step tutorial that takes you from an empty project to deploying your first application.
- Core Concepts: A high-level overview of the key concepts in Harmony:
Score,Topology,Capability,Inventory,Interpret, ...
2. Use Cases & Examples
See how to use Harmony to solve real-world problems.
- OPNsense VM Integration: Boot a real OPNsense firewall in a local KVM VM and configure it entirely through Harmony. Fully automated, zero manual steps — the flashiest demo. Requires Linux with KVM.
- PostgreSQL on Local K3D: Deploy a production-grade PostgreSQL cluster on a local K3D cluster. The fastest way to get started.
- OKD on Bare Metal: A detailed walkthrough of bootstrapping a high-availability OKD cluster from physical hardware.
3. Component Catalogs
Discover existing, reusable components you can use in your Harmony projects.
- Scores Catalog: A categorized list of all available
Scores(the "what"). - Topologies Catalog: A list of all available
Topologies(the "where"). - Capabilities Catalog: A list of all available
Capabilities(the "how").
4. Developer Guides
Ready to build your own components? These guides show you how.
- Writing a Score: Learn how to create your own
ScoreandInterpretlogic to define a new desired state. - Writing a Topology: Learn how to model a new environment (like AWS, GCP, or custom hardware) as a
Topology. - Adding Capabilities: See how to add a
Capabilityto your customTopology.
5. Architecture Decision Records
Harmony's design is documented through Architecture Decision Records (ADRs). See the ADR Overview for a complete index of all decisions.