From 54990cd1a56370dd35b3461f6f2ed306b01acc31 Mon Sep 17 00:00:00 2001 From: Ian Letourneau Date: Mon, 4 Aug 2025 20:59:07 +0000 Subject: [PATCH] fix(cli): simplify running the CLI by hiding the maestro inside the implemtation (#93) Co-authored-by: Ian Letourneau Reviewed-on: https://git.nationtech.io/NationTech/harmony/pulls/93 --- README.md | 73 ++++++++++----------- examples/cli/src/main.rs | 23 +++---- examples/lamp/src/main.rs | 9 +-- examples/monitoring/src/main.rs | 9 ++- examples/monitoring_with_tenant/src/main.rs | 9 ++- examples/ntfy/src/main.rs | 16 ++--- examples/rust/src/main.rs | 21 +++--- examples/tenant/src/main.rs | 8 +-- harmony/src/domain/maestro/mod.rs | 2 +- harmony_cli/src/lib.rs | 24 ++++++- 10 files changed, 99 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index b31f541..e77718e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ -# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code. -*By [NationTech](https://nationtech.io)* +# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code + +_By [NationTech](https://nationtech.io)_ [![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/nationtech/harmony) [![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)](LICENSE) @@ -23,11 +24,11 @@ From a **developer laptop** to a **global production cluster**, a single **sourc Infrastructure is essential, but it shouldn’t be your core business. Harmony is built on three guiding principles that make modern platforms reliable, repeatable, and easy to reason about. -| Principle | What it means for you | -|-----------|-----------------------| -| **Infrastructure as Resilient Code** | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code. | -| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages. | -| **One Unified Model** | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. | +| Principle | What it means for you | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Infrastructure as Resilient Code** | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code. | +| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages. | +| **One Unified Model** | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. | These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath. @@ -63,22 +64,20 @@ async fn main() { }, }; - // 2. Pick where it should run - let mut maestro = Maestro::::initialize( - Inventory::autoload(), // auto-detect hardware / kube-config - K8sAnywhereTopology::from_env(), // local k3d, CI, staging, prod… - ) - .await - .unwrap(); - - // 3. Enhance with extra scores (monitoring, CI/CD, …) + // 2. Enhance with extra scores (monitoring, CI/CD, …) let mut monitoring = MonitoringAlertingStackScore::new(); monitoring.namespace = Some(lamp_stack.config.namespace.clone()); - maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring)]); - - // 4. Launch an interactive CLI / TUI - harmony_cli::init(maestro, None).await.unwrap(); + // 3. Run your scores on the desired topology & inventory + harmony_cli::run( + Inventory::autoload(), // auto-detect hardware / kube-config + K8sAnywhereTopology::from_env(), // local k3d, CI, staging, prod… + vec![ + Box::new(lamp_stack), + Box::new(monitoring) + ], + None + ).await.unwrap(); } ``` @@ -94,13 +93,13 @@ Harmony analyses the code, shows an execution plan in a TUI, and applies it once ## 3 · Core Concepts -| Term | One-liner | -|------|-----------| -| **Score** | Declarative description of the desired state (e.g., `LAMPScore`). | -| **Interpret** | Imperative logic that realises a `Score` on a specific environment. | -| **Topology** | An environment (local k3d, AWS, bare-metal) exposing verified *Capabilities* (Kubernetes, DNS, …). | -| **Maestro** | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. | -| **Inventory** | Optional catalogue of physical assets for bare-metal and edge deployments. | +| Term | One-liner | +| ---------------- | ---------------------------------------------------------------------------------------------------- | +| **Score** | Declarative description of the desired state (e.g., `LAMPScore`). | +| **Interpret** | Imperative logic that realises a `Score` on a specific environment. | +| **Topology** | An environment (local k3d, AWS, bare-metal) exposing verified _Capabilities_ (Kubernetes, DNS, …). | +| **Maestro** | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. | +| **Inventory** | Optional catalogue of physical assets for bare-metal and edge deployments. | A visual overview is in the diagram below. @@ -112,9 +111,9 @@ A visual overview is in the diagram below. Prerequisites: -* Rust -* Docker (if you deploy locally) -* `kubectl` / `helm` for Kubernetes-based topologies +- Rust +- Docker (if you deploy locally) +- `kubectl` / `helm` for Kubernetes-based topologies ```bash git clone https://git.nationtech.io/nationtech/harmony @@ -126,15 +125,15 @@ cargo build --release # builds the CLI, TUI and libraries ## 5 · Learning More -* **Architectural Decision Records** – dive into the rationale - - [ADR-001 · Why Rust](adr/001-rust.md) - - [ADR-003 · Infrastructure Abstractions](adr/003-infrastructure-abstractions.md) - - [ADR-006 · Secret Management](adr/006-secret-management.md) +- **Architectural Decision Records** – dive into the rationale + - [ADR-001 · Why Rust](adr/001-rust.md) + - [ADR-003 · Infrastructure Abstractions](adr/003-infrastructure-abstractions.md) + - [ADR-006 · Secret Management](adr/006-secret-management.md) - [ADR-011 · Multi-Tenant Cluster](adr/011-multi-tenant-cluster.md) -* **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`). +- **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`). -* **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome! +- **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome! --- @@ -148,4 +147,4 @@ See [LICENSE](LICENSE) for the full text. --- -*Made with ❤️ & 🦀 by the NationTech and the Harmony community* +_Made with ❤️ & 🦀 by the NationTech and the Harmony community_ diff --git a/examples/cli/src/main.rs b/examples/cli/src/main.rs index 58674ff..34a032b 100644 --- a/examples/cli/src/main.rs +++ b/examples/cli/src/main.rs @@ -1,20 +1,21 @@ use harmony::{ inventory::Inventory, - maestro::Maestro, modules::dummy::{ErrorScore, PanicScore, SuccessScore}, topology::LocalhostTopology, }; #[tokio::main] async fn main() { - let inventory = Inventory::autoload(); - let topology = LocalhostTopology::new(); - let mut maestro = Maestro::initialize(inventory, topology).await.unwrap(); - - maestro.register_all(vec![ - Box::new(SuccessScore {}), - Box::new(ErrorScore {}), - Box::new(PanicScore {}), - ]); - harmony_cli::init(maestro, None).await.unwrap(); + harmony_cli::run( + Inventory::autoload(), + LocalhostTopology::new(), + vec![ + Box::new(SuccessScore {}), + Box::new(ErrorScore {}), + Box::new(PanicScore {}), + ], + None, + ) + .await + .unwrap(); } diff --git a/examples/lamp/src/main.rs b/examples/lamp/src/main.rs index 51816e6..6662f4c 100644 --- a/examples/lamp/src/main.rs +++ b/examples/lamp/src/main.rs @@ -1,7 +1,6 @@ use harmony::{ data::Version, inventory::Inventory, - maestro::Maestro, modules::lamp::{LAMPConfig, LAMPScore}, topology::{K8sAnywhereTopology, Url}, }; @@ -43,15 +42,13 @@ async fn main() { // K8sAnywhereTopology as it is the most automatic one that enables you to easily deploy // locally, to development environment from a CI, to staging, and to production with settings // that automatically adapt to each environment grade. - let mut maestro = Maestro::::initialize( + harmony_cli::run( Inventory::autoload(), K8sAnywhereTopology::from_env(), + vec![Box::new(lamp_stack)], + None, ) .await .unwrap(); - - maestro.register_all(vec![Box::new(lamp_stack)]); - // Here we bootstrap the CLI, this gives some nice features if you need them - harmony_cli::init(maestro, None).await.unwrap(); } // That's it, end of the infra as code. diff --git a/examples/monitoring/src/main.rs b/examples/monitoring/src/main.rs index 989b1ec..d59a0ef 100644 --- a/examples/monitoring/src/main.rs +++ b/examples/monitoring/src/main.rs @@ -2,7 +2,6 @@ use std::collections::HashMap; use harmony::{ inventory::Inventory, - maestro::Maestro, modules::{ monitoring::{ alert_channel::discord_alert_channel::DiscordWebhook, @@ -74,13 +73,13 @@ async fn main() { rules: vec![Box::new(additional_rules), Box::new(additional_rules2)], service_monitors: vec![service_monitor], }; - let mut maestro = Maestro::::initialize( + + harmony_cli::run( Inventory::autoload(), K8sAnywhereTopology::from_env(), + vec![Box::new(alerting_score)], + None, ) .await .unwrap(); - - maestro.register_all(vec![Box::new(alerting_score)]); - harmony_cli::init(maestro, None).await.unwrap(); } diff --git a/examples/monitoring_with_tenant/src/main.rs b/examples/monitoring_with_tenant/src/main.rs index ec80542..d234682 100644 --- a/examples/monitoring_with_tenant/src/main.rs +++ b/examples/monitoring_with_tenant/src/main.rs @@ -3,7 +3,6 @@ use std::collections::HashMap; use harmony::{ data::Id, inventory::Inventory, - maestro::Maestro, modules::{ monitoring::{ alert_channel::discord_alert_channel::DiscordWebhook, @@ -78,13 +77,13 @@ async fn main() { rules: vec![Box::new(additional_rules)], service_monitors: vec![service_monitor], }; - let mut maestro = Maestro::::initialize( + + harmony_cli::run( Inventory::autoload(), K8sAnywhereTopology::from_env(), + vec![Box::new(tenant), Box::new(alerting_score)], + None, ) .await .unwrap(); - - maestro.register_all(vec![Box::new(tenant), Box::new(alerting_score)]); - harmony_cli::init(maestro, None).await.unwrap(); } diff --git a/examples/ntfy/src/main.rs b/examples/ntfy/src/main.rs index fc04e6e..3601706 100644 --- a/examples/ntfy/src/main.rs +++ b/examples/ntfy/src/main.rs @@ -1,20 +1,18 @@ use harmony::{ - inventory::Inventory, maestro::Maestro, modules::monitoring::ntfy::ntfy::NtfyScore, - topology::K8sAnywhereTopology, + inventory::Inventory, modules::monitoring::ntfy::ntfy::NtfyScore, topology::K8sAnywhereTopology, }; #[tokio::main] async fn main() { - let mut maestro = Maestro::::initialize( + harmony_cli::run( Inventory::autoload(), K8sAnywhereTopology::from_env(), + vec![Box::new(NtfyScore { + namespace: "monitoring".to_string(), + host: "localhost".to_string(), + })], + None, ) .await .unwrap(); - - maestro.register_all(vec![Box::new(NtfyScore { - namespace: "monitoring".to_string(), - host: "localhost".to_string(), - })]); - harmony_cli::init(maestro, None).await.unwrap(); } diff --git a/examples/rust/src/main.rs b/examples/rust/src/main.rs index 94eb8a7..2747a3d 100644 --- a/examples/rust/src/main.rs +++ b/examples/rust/src/main.rs @@ -2,24 +2,15 @@ use std::{path::PathBuf, sync::Arc}; use harmony::{ inventory::Inventory, - maestro::Maestro, modules::application::{ ApplicationScore, RustWebFramework, RustWebapp, features::{ContinuousDelivery, Monitoring}, }, topology::{K8sAnywhereTopology, Url}, }; -use harmony_cli::cli_logger; #[tokio::main] async fn main() { - let cli_logger_handle = cli_logger::init(); - - let topology = K8sAnywhereTopology::from_env(); - let mut maestro = Maestro::initialize(Inventory::autoload(), topology) - .await - .unwrap(); - let application = Arc::new(RustWebapp { name: "harmony-example-rust-webapp".to_string(), domain: Url::Url(url::Url::parse("https://rustapp.harmony.example.com").unwrap()), @@ -39,8 +30,12 @@ async fn main() { application, }; - maestro.register_all(vec![Box::new(app)]); - harmony_cli::init(maestro, None).await.unwrap(); - - let _ = tokio::try_join!(cli_logger_handle); + harmony_cli::run( + Inventory::autoload(), + K8sAnywhereTopology::from_env(), + vec![Box::new(app)], + None, + ) + .await + .unwrap(); } diff --git a/examples/tenant/src/main.rs b/examples/tenant/src/main.rs index e5ac36c..b5202b2 100644 --- a/examples/tenant/src/main.rs +++ b/examples/tenant/src/main.rs @@ -1,7 +1,6 @@ use harmony::{ data::Id, inventory::Inventory, - maestro::Maestro, modules::tenant::TenantScore, topology::{K8sAnywhereTopology, tenant::TenantConfig}, }; @@ -16,15 +15,14 @@ async fn main() { }, }; - let mut maestro = Maestro::::initialize( + harmony_cli::run( Inventory::autoload(), K8sAnywhereTopology::from_env(), + vec![Box::new(tenant)], + None, ) .await .unwrap(); - - maestro.register_all(vec![Box::new(tenant)]); - harmony_cli::init(maestro, None).await.unwrap(); } // TODO write tests diff --git a/harmony/src/domain/maestro/mod.rs b/harmony/src/domain/maestro/mod.rs index a7f2b60..4d1053e 100644 --- a/harmony/src/domain/maestro/mod.rs +++ b/harmony/src/domain/maestro/mod.rs @@ -1,6 +1,6 @@ use std::sync::{Arc, Mutex, RwLock}; -use log::{debug, info, warn}; +use log::{debug, warn}; use crate::instrumentation::{self, HarmonyEvent}; diff --git a/harmony_cli/src/lib.rs b/harmony_cli/src/lib.rs index 4d71a6e..1fea271 100644 --- a/harmony_cli/src/lib.rs +++ b/harmony_cli/src/lib.rs @@ -1,8 +1,10 @@ use clap::Parser; use clap::builder::ArgPredicate; -use harmony; +use harmony::inventory::Inventory; +use harmony::maestro::Maestro; use harmony::{score::Score, topology::Topology}; use inquire::Confirm; +use log::debug; pub mod cli_logger; // FIXME: Don't make me pub pub mod progress; @@ -10,7 +12,6 @@ pub mod theme; #[cfg(feature = "tui")] use harmony_tui; -use log::debug; #[derive(Parser, Debug)] #[command(version, about, long_about = None)] @@ -85,7 +86,24 @@ fn list_scores_with_index(scores_vec: &Vec>>) -> S return display_str; } -pub async fn init( +pub async fn run( + inventory: Inventory, + topology: T, + scores: Vec>>, + args_struct: Option, +) -> Result<(), Box> { + let cli_logger_handle = cli_logger::init(); + + let mut maestro = Maestro::initialize(inventory, topology).await.unwrap(); + maestro.register_all(scores); + + let result = init(maestro, args_struct).await; + + let _ = tokio::try_join!(cli_logger_handle); + result +} + +async fn init( maestro: harmony::maestro::Maestro, args_struct: Option, ) -> Result<(), Box> {