Jean-Gabriel Gill-Couture
020ebcb1f9
The previous e2e harness handrolled k8s manifests in `stack.rs`,
bypassing the Score-Topology-Interpret machinery harmony exists to
provide. This commit:
1. **ADR-023** codifies the rules: deploy with Scores (not
manifests), e2e uses the same Scores as production, one Score
per component, deploy blocks on smoke-test success, deploy logic
lives in `*-deploy` crates, topologies are compile-time,
thiserror over anyhow. CLAUDE.md mirrors the principles.
2. **New `fleet/harmony-fleet-deploy` crate** is the canonical home
for fleet-component Scores:
- `FleetOperatorScore` + helm-chart generator + `install_crds`
moved out of `harmony::modules::fleet::operator` (they should
never have lived in `harmony` core). `FleetServerScore`
(composite of NATS + operator + Zitadel + callout) moved too.
- New `FleetNatsScore` (preset over `NatsHelmChartScore` with
fleet's required values; v1 supports `UserPass` auth, callout
mode reserved on the public API for PR 1.5).
- New `FleetAgentScore` with `FleetAgentTarget::Pod`; `Vm`
target is a future variant that absorbs `FleetDeviceSetupScore`.
- `harmony-fleet-deploy` binary built on the existing
`harmony_cli` crate — no new CLI scaffolding.
3. **Operator runtime binary trimmed**: `Install` and `Chart`
subcommands removed; both jobs now belong to
`harmony-fleet-deploy`. The runtime binary becomes leaner.
4. **E2E harness rewritten** as a thin Score composer:
`harmony-fleet-e2e/src/stack.rs` deploys the stack via
`FleetNatsScore` + `FleetAgentScore`. The inline NATS manifest
factory and the bespoke agent Pod renderer are gone.
- Bring-up runs once per test binary via `shared_stack` +
`tokio::sync::OnceCell` (matches the `fleet_e2e_demo` pattern).
- Stale `e2e-*` namespaces from prior runs get pruned at
startup so the leaks the OnceCell creates don't compound.
5. **`thiserror` for the agent's `CommandServer`** — replaces the
anyhow-based surface with typed `CommandError` /
`CommandServerError`.
6. **Memory** captures eight load-bearing principles (saved to
`~/.claude/projects/.../memory/`) so future sessions don't drift
back into manifest-handrolling.
Verified: `cargo test -p harmony-fleet-e2e --test ping` green
end-to-end against k3d in 25s warm.
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.