wip: improving inventory discovery

Reviewed-on: #233

.dockerignore

@@ -1,2 +1,6 @@
 target/
-Dockerfile
+Dockerfile
+.git
+data
+target
+demos

.gitattributes

@@ -2,3 +2,5 @@ bootx64.efi filter=lfs diff=lfs merge=lfs -text
 grubx64.efi filter=lfs diff=lfs merge=lfs -text
 initrd filter=lfs diff=lfs merge=lfs -text
 linux filter=lfs diff=lfs merge=lfs -text
+data/okd/bin/* filter=lfs diff=lfs merge=lfs -text
+data/okd/installer_image/* filter=lfs diff=lfs merge=lfs -text

.gitea/workflows/check.yml

@@ -9,7 +9,7 @@ jobs:
   check:
     runs-on: docker
     container:
-      image: hub.nationtech.io/harmony/harmony_composer:latest@sha256:eb0406fcb95c63df9b7c4b19bc50ad7914dd8232ce98e9c9abef628e07c69386
+      image: hub.nationtech.io/harmony/harmony_composer:latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitea/workflows/harmony_composer.yaml

@@ -7,7 +7,7 @@ on:
 jobs:
   package_harmony_composer:
     container:
-      image: hub.nationtech.io/harmony/harmony_composer:latest@sha256:eb0406fcb95c63df9b7c4b19bc50ad7914dd8232ce98e9c9abef628e07c69386
+      image: hub.nationtech.io/harmony/harmony_composer:latest
     runs-on: dind
     steps:
       - name: Checkout code
@@ -45,14 +45,14 @@ jobs:
             -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
             "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/tags/snapshot-latest" \
             | jq -r '.id // empty')
-          
+
           if [ -n "$RELEASE_ID" ]; then
             # Delete existing release
             curl -X DELETE \
               -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
               "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/$RELEASE_ID"
           fi
-          
+
           # Create new release
           RESPONSE=$(curl -X POST \
             -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
@@ -65,7 +65,7 @@ jobs:
               "prerelease": true
             }' \
             "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases")
-          
+
           echo "RELEASE_ID=$(echo $RESPONSE | jq -r '.id')" >> $GITHUB_ENV
 
       - name: Upload Linux binary

.gitignore

@@ -1,5 +1,31 @@
-target
-private_repos
-log/
-*.tgz
-.gitignore
+### General ###
+private_repos/
+
+### Harmony ###
+harmony.log
+data/okd/installation_files*
+
+### Helm ###
+# Chart dependencies
+**/charts/*.tgz
+
+### Rust ###
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+.harmony_generated
+
+# Useful to create ignore folders for temp files and notes
+ignore

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "examples/try_rust_webapp/tryrust.org"]
+	path = examples/try_rust_webapp/tryrust.org
+	url = https://github.com/rust-dd/tryrust.org.git

.sqlx/query-24f719d57144ecf4daa55f0aa5836c165872d70164401c0388e8d625f1b72d7b.json

@@ -0,0 +1,26 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT host_id, installation_device FROM host_role_mapping WHERE role = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "host_id",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "installation_device",
+        "ordinal": 1,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true
+    ]
+  },
+  "hash": "24f719d57144ecf4daa55f0aa5836c165872d70164401c0388e8d625f1b72d7b"
+}

.sqlx/query-6fcc29cfdbdf3b2cee94a4844e227f09b245dd8f079832a9a7b774151cb03af6.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "\n        INSERT INTO host_role_mapping (host_id, role, installation_device)\n        VALUES (?, ?, ?)\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "6fcc29cfdbdf3b2cee94a4844e227f09b245dd8f079832a9a7b774151cb03af6"
+}

.sqlx/query-8d247918eca10a88b784ee353db090c94a222115c543231f2140cba27bd0f067.json

@@ -0,0 +1,32 @@
+{
+  "db_name": "SQLite",
+  "query": "\n        SELECT\n            p1.id,\n            p1.version_id,\n            p1.data as \"data: Json<PhysicalHost>\"\n        FROM\n            physical_hosts p1\n        INNER JOIN (\n            SELECT\n                id,\n                MAX(version_id) AS max_version\n            FROM\n                physical_hosts\n            GROUP BY\n                id\n        ) p2 ON p1.id = p2.id AND p1.version_id = p2.max_version\n        ",
+  "describe": {
+    "columns": [
+      {
+        "name": "id",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "version_id",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "data: Json<PhysicalHost>",
+        "ordinal": 2,
+        "type_info": "Blob"
+      }
+    ],
+    "parameters": {
+      "Right": 0
+    },
+    "nullable": [
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "8d247918eca10a88b784ee353db090c94a222115c543231f2140cba27bd0f067"
+}

.sqlx/query-934035c7ca6e064815393e4e049a7934b0a7fac04a4fe4b2a354f0443d630990.json

@@ -0,0 +1,32 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT id, version_id, data as \"data: Json<PhysicalHost>\" FROM physical_hosts WHERE id = ? ORDER BY version_id DESC LIMIT 1",
+  "describe": {
+    "columns": [
+      {
+        "name": "id",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "version_id",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "data: Json<PhysicalHost>",
+        "ordinal": 2,
+        "type_info": "Null"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "934035c7ca6e064815393e4e049a7934b0a7fac04a4fe4b2a354f0443d630990"
+}

.sqlx/query-f10f615ee42129ffa293e46f2f893d65a237d31d24b74a29c6a8d8420d255ab8.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO physical_hosts (id, version_id, data) VALUES (?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "f10f615ee42129ffa293e46f2f893d65a237d31d24b74a29c6a8d8420d255ab8"
+}

Cargo.toml

@@ -7,11 +7,19 @@ members = [
   "harmony_types",
   "harmony_macros",
   "harmony_tui",
+  "harmony_execution",
   "opnsense-config",
   "opnsense-config-xml",
   "harmony_cli",
   "k3d",
   "harmony_composer",
+  "harmony_inventory_agent",
+  "harmony_secret_derive",
+  "harmony_secret",
+  "adr/agent_discovery/mdns",
+  "brocade",
+  "harmony_agent",
+  "harmony_agent/deploy",
 ]
 
 [workspace.package]
@@ -20,7 +28,7 @@ readme = "README.md"
 license = "GNU AGPL v3"
 
 [workspace.dependencies]
-log = "0.4"
+log = { version = "0.4", features = ["kv"] }
 env_logger = "0.11"
 derive-new = "0.7"
 async-trait = "0.1"
@@ -33,7 +41,7 @@ tokio = { version = "1.40", features = [
 cidr = { features = ["serde"], version = "0.2" }
 russh = "0.45"
 russh-keys = "0.45"
-rand = "0.8"
+rand = "0.9"
 url = "2.5"
 kube = { version = "1.1.0", features = [
   "config",
@@ -44,6 +52,7 @@ kube = { version = "1.1.0", features = [
   "jsonpatch",
 ] }
 k8s-openapi = { version = "0.25", features = ["v1_30"] }
+# TODO replace with https://github.com/bourumir-wyngs/serde-saphyr as serde_yaml is deprecated https://github.com/sebastienrousseau/serde_yml
 serde_yaml = "0.9"
 serde-value = "0.7"
 http = "1.2"
@@ -53,6 +62,22 @@ chrono = "0.4"
 similar = "2"
 uuid = { version = "1.11", features = ["v4", "fast-rng", "macro-diagnostics"] }
 pretty_assertions = "1.4.1"
+tempfile = "3.20.0"
 bollard = "0.19.1"
 base64 = "0.22.1"
 tar = "0.4.44"
+lazy_static = "1.5.0"
+directories = "6.0.0"
+thiserror = "2.0.14"
+serde = { version = "1.0.209", features = ["derive", "rc"] }
+serde_json = "1.0.127"
+askama = "0.14"
+sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite"] }
+reqwest = { version = "0.12", features = [
+  "blocking",
+  "stream",
+  "rustls-tls",
+  "http2",
+  "json",
+], default-features = false }
+assertor = "0.0.4"

Dockerfile

@@ -1,4 +1,4 @@
-FROM docker.io/rust:1.87.0 AS build
+FROM docker.io/rust:1.89.0 AS build
 
 WORKDIR /app
 
@@ -6,13 +6,14 @@ COPY . .
 
 RUN cargo build --release --bin harmony_composer
 
-FROM docker.io/rust:1.87.0
+FROM docker.io/rust:1.89.0
 
 WORKDIR /app
 
 RUN rustup target add x86_64-pc-windows-gnu
 RUN rustup target add x86_64-unknown-linux-gnu
 RUN rustup component add rustfmt
+RUN rustup component add clippy
 
 RUN apt update
 
@@ -22,4 +23,4 @@ RUN apt install -y nodejs docker.io mingw-w64
 
 COPY --from=build /app/target/release/harmony_composer .
 
-ENTRYPOINT ["/app/harmony_composer"]
+ENTRYPOINT ["/app/harmony_composer"]

README.md

@@ -1,5 +1,10 @@
-# 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.
+
+In other words, Harmony is a **next-generation platform engineering framework**.
+
+_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)
@@ -17,128 +22,114 @@ All in **one strongly-typed Rust codebase**.
 
 From a **developer laptop** to a **global production cluster**, a single **source of truth** drives the **full software lifecycle.**
 
----
-
-## 1 · The Harmony Philosophy
+## The Harmony Philosophy
 
 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.
 
----
+## Where to Start
 
-## 2 · Quick Start
+We have a comprehensive set of documentation right here in the repository.
 
-The snippet below spins up a complete **production-grade LAMP stack** with monitoring. Swap it for your own scores to deploy anything from microservices to machine-learning pipelines.
+| I want to...      | Start Here                                                         |
+| ----------------- | ------------------------------------------------------------------ |
+| Get Started       | [Getting Started Guide](./docs/guides/getting-started.md)          |
+| See an Example    | [Use Case: Deploy a Rust Web App](./docs/use-cases/rust-webapp.md) |
+| Explore           | [Documentation Hub](./docs/README.md)                              |
+| See Core Concepts | [Core Concepts Explained](./docs/concepts.md)                      |
+
+## Quick Look: Deploy a Rust Webapp
+
+The snippet below spins up a complete **production-grade Rust + Leptos Webapp** with monitoring. Swap it for your own scores to deploy anything from microservices to machine-learning pipelines.
 
 ```rust
 use harmony::{
-    data::Version,
     inventory::Inventory,
-    maestro::Maestro,
     modules::{
-        lamp::{LAMPConfig, LAMPScore},
-        monitoring::monitoring_alerting::MonitoringAlertingStackScore,
+        application::{
+            ApplicationScore, RustWebFramework, RustWebapp,
+            features::{PackagingDeployment, rhob_monitoring::Monitoring},
+        },
+        monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
     },
-    topology::{K8sAnywhereTopology, Url},
+    topology::K8sAnywhereTopology,
 };
+use harmony_macros::hurl;
+use std::{path::PathBuf, sync::Arc};
 
 #[tokio::main]
 async fn main() {
-    // 1. Describe what you want
-    let lamp_stack = LAMPScore {
-        name: "harmony-lamp-demo".into(),
-        domain: Url::Url(url::Url::parse("https://lampdemo.example.com").unwrap()),
-        php_version: Version::from("8.3.0").unwrap(),
-        config: LAMPConfig {
-            project_root: "./php".into(),
-            database_size: "4Gi".into(),
-            ..Default::default()
-        },
+    let application = Arc::new(RustWebapp {
+        name: "harmony-example-leptos".to_string(),
+        project_root: PathBuf::from(".."), // <== Your project root, usually .. if you use the standard `/harmony` folder
+        framework: Some(RustWebFramework::Leptos),
+        service_port: 8080,
+    });
+
+    // Define your Application deployment and the features you want
+    let app = ApplicationScore {
+        features: vec![
+            Box::new(PackagingDeployment {
+                application: application.clone(),
+            }),
+            Box::new(Monitoring {
+                application: application.clone(),
+                alert_receiver: vec![
+                    Box::new(DiscordWebhook {
+                        name: "test-discord".to_string(),
+                        url: hurl!("https://discord.doesnt.exist.com"), // <== Get your discord webhook url
+                    }),
+                ],
+            }),
+        ],
+        application,
     };
 
-    // 2. Pick where it should run
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
-        Inventory::autoload(),                // auto-detect hardware / kube-config
-        K8sAnywhereTopology::from_env(),      // local k3d, CI, staging, prod…
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(), // <== Deploy to local automatically provisioned local k3d by default or connect to any kubernetes cluster
+        vec![Box::new(app)],
+        None,
     )
     .await
     .unwrap();
-
-    // 3. 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();
 }
 ```
 
-Run it:
+To run this:
 
-```bash
-cargo run
-```
+- Clone the repository: `git clone https://git.nationtech.io/nationtech/harmony`
+- Install dependencies: `cargo build --release`
+- Run the example: `cargo run --example try_rust_webapp`
 
-Harmony analyses the code, shows an execution plan in a TUI, and applies it once you confirm. Same code, same binary—every environment.
+## Documentation
 
----
+All documentation is in the `/docs` directory.
 
-## 3 · Core Concepts
+- [Documentation Hub](./docs/README.md): The main entry point for all documentation.
+- [Core Concepts](./docs/concepts.md): A detailed look at Score, Topology, Capability, Inventory, and Interpret.
+- [Component Catalogs](./docs/catalogs/README.md): Discover all available Scores, Topologies, and Capabilities.
+- [Developer Guide](./docs/guides/developer-guide.md): Learn how to write your own Scores and Topologies.
 
-| Term | One-liner |
-|------|-----------|
-| **Score<T>** | Declarative description of the desired state (e.g., `LAMPScore`). |
-| **Interpret<T>** | 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. |
+## Architectural Decision Records
 
-A visual overview is in the diagram below.
+- [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)
 
-[Harmony Core Architecture](docs/diagrams/Harmony_Core_Architecture.drawio.svg)
+## Contribute
 
----
+Discussions and roadmap live in [Issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
 
-## 4 · Install
-
-Prerequisites:
-
-* Rust 
-* Docker (if you deploy locally)
-* `kubectl` / `helm` for Kubernetes-based topologies
-
-```bash
-git clone https://git.nationtech.io/nationtech/harmony
-cd harmony
-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)  
-  - [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`).
-
-* **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
-
----
-
-## 6 · License
+## License
 
 Harmony is released under the **GNU AGPL v3**.
 
@@ -148,4 +139,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_

adr/015-higher-order-topologies.md

@@ -0,0 +1,114 @@
+# Architecture Decision Record: Higher-Order Topologies
+
+**Initial Author:** Jean-Gabriel Gill-Couture  
+**Initial Date:** 2025-12-08  
+**Last Updated Date:** 2025-12-08  
+
+## Status
+
+Implemented
+
+## Context
+
+Harmony models infrastructure as **Topologies** (deployment targets like `K8sAnywhereTopology`, `LinuxHostTopology`) implementing **Capabilities** (tech traits like `PostgreSQL`, `Docker`).
+
+**Higher-Order Topologies** (e.g., `FailoverTopology<T>`) compose/orchestrate capabilities *across* multiple underlying topologies (e.g., primary+replica `T`).
+
+Naive design requires manual `impl Capability for HigherOrderTopology<T>` *per T per capability*, causing:
+- **Impl explosion**: N topologies × M capabilities = N×M boilerplate.
+- **ISP violation**: Topologies forced to impl unrelated capabilities.
+- **Maintenance hell**: New topology needs impls for *all* orchestrated capabilities; new capability needs impls for *all* topologies/higher-order.
+- **Barrier to extension**: Users can't easily add topologies without todos/panics.
+
+This makes scaling Harmony impractical as ecosystem grows.
+
+## Decision
+
+Use **blanket trait impls** on higher-order topologies to *automatically* derive orchestration:
+
+````rust
+/// Higher-Order Topology: Orchestrates capabilities across sub-topologies.
+pub struct FailoverTopology<T> {
+    /// Primary sub-topology.
+    primary: T,
+    /// Replica sub-topology.
+    replica: T,
+}
+
+/// Automatically provides PostgreSQL failover for *any* `T: PostgreSQL`.
+/// Delegates to primary for queries; orchestrates deploy across both.
+#[async_trait]
+impl<T: PostgreSQL> PostgreSQL for FailoverTopology<T> {
+    async fn deploy(&self, config: &PostgreSQLConfig) -> Result<String, String> {
+        // Deploy primary; extract certs/endpoint;
+        // deploy replica with pg_basebackup + TLS passthrough.
+        // (Full impl logged/elaborated.)
+    }
+
+    // Delegate queries to primary.
+    async fn get_replication_certs(&self, cluster_name: &str) -> Result<ReplicationCerts, String> {
+        self.primary.get_replication_certs(cluster_name).await
+    }
+    // ...
+}
+
+/// Similarly for other capabilities.
+#[async_trait]
+impl<T: Docker> Docker for FailoverTopology<T> {
+    // Failover Docker orchestration.
+}
+````
+
+**Key properties:**
+- **Auto-derivation**: `Failover<K8sAnywhere>` gets `PostgreSQL` iff `K8sAnywhere: PostgreSQL`.
+- **No boilerplate**: One blanket impl per capability *per higher-order type*.
+
+## Rationale
+
+- **Composition via generics**: Rust trait solver auto-selects impls; zero runtime cost.
+- **Compile-time safety**: Missing `T: Capability` → compile error (no panics).
+- **Scalable**: O(capabilities) impls per higher-order; new `T` auto-works.
+- **ISP-respecting**: Capabilities only surface if sub-topology provides.
+- **Centralized logic**: Orchestration (e.g., cert propagation) in one place.
+
+**Example usage:**
+````rust
+// ✅ Works: K8sAnywhere: PostgreSQL → Failover provides failover PG
+let pg_failover: FailoverTopology<K8sAnywhereTopology> = ...;
+pg_failover.deploy_pg(config).await;
+
+// ✅ Works: LinuxHost: Docker → Failover provides failover Docker
+let docker_failover: FailoverTopology<LinuxHostTopology> = ...;
+docker_failover.deploy_docker(...).await;
+
+// ❌ Compile fail: K8sAnywhere !: Docker
+let invalid: FailoverTopology<K8sAnywhereTopology>;
+invalid.deploy_docker(...); // `T: Docker` bound unsatisfied
+````
+
+## Consequences
+
+**Pros:**
+- **Extensible**: New topology `AWSTopology: PostgreSQL` → instant `Failover<AWSTopology>: PostgreSQL`.
+- **Lean**: No useless impls (e.g., no `K8sAnywhere: Docker`).
+- **Observable**: Logs trace every step.
+
+**Cons:**
+- **Monomorphization**: Generics generate code per T (mitigated: few Ts).
+- **Delegation opacity**: Relies on rustdoc/logs for internals.
+
+## Alternatives considered
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Manual per-T impls**<br>`impl PG for Failover<K8s> {..}`<br>`impl PG for Failover<Linux> {..}` | Explicit control | N×M explosion; violates ISP; hard to extend. |
+| **Dynamic trait objects**<br>`Box<dyn AnyCapability>` | Runtime flex | Perf hit; type erasure; error-prone dispatch. |
+| **Mega-topology trait**<br>All-in-one `OrchestratedTopology` | Simple wiring | Monolithic; poor composition. |
+| **Registry dispatch**<br>Runtime capability lookup | Decoupled | Complex; no compile safety; perf/debug overhead. |
+
+**Selected**: Blanket impls leverage Rust generics for safe, zero-cost composition.
+
+## Additional Notes
+
+- Applies to `MultisiteTopology<T>`, `ShardedTopology<T>`, etc.
+- `FailoverTopology` in `failover.rs` is first implementation.

adr/015-higher-order-topologies/example.rs

@@ -0,0 +1,153 @@
+//! Example of Higher-Order Topologies in Harmony.
+//! Demonstrates how `FailoverTopology<T>` automatically provides failover for *any* capability
+//! supported by a sub-topology `T` via blanket trait impls.
+//! 
+//! Key insight: No manual impls per T or capability -- scales effortlessly.
+//! Users can:
+//! - Write new `Topology` (impl capabilities on a struct).
+//! - Compose with `FailoverTopology` (gets capabilities if T has them).
+//! - Compile fails if capability missing (safety).
+
+use async_trait::async_trait;
+use tokio;
+
+/// Capability trait: Deploy and manage PostgreSQL.
+#[async_trait]
+pub trait PostgreSQL {
+    async fn deploy(&self, config: &PostgreSQLConfig) -> Result<String, String>;
+    async fn get_replication_certs(&self, cluster_name: &str) -> Result<ReplicationCerts, String>;
+}
+
+/// Capability trait: Deploy Docker.
+#[async_trait]
+pub trait Docker {
+    async fn deploy_docker(&self) -> Result<String, String>;
+}
+
+/// Configuration for PostgreSQL deployments.
+#[derive(Clone)]
+pub struct PostgreSQLConfig;
+
+/// Replication certificates.
+#[derive(Clone)]
+pub struct ReplicationCerts;
+
+/// Concrete topology: Kubernetes Anywhere (supports PostgreSQL).
+#[derive(Clone)]
+pub struct K8sAnywhereTopology;
+
+#[async_trait]
+impl PostgreSQL for K8sAnywhereTopology {
+    async fn deploy(&self, _config: &PostgreSQLConfig) -> Result<String, String> {
+        // Real impl: Use k8s helm chart, operator, etc.
+        Ok("K8sAnywhere PostgreSQL deployed".to_string())
+    }
+
+    async fn get_replication_certs(&self, _cluster_name: &str) -> Result<ReplicationCerts, String> {
+        Ok(ReplicationCerts)
+    }
+}
+
+/// Concrete topology: Linux Host (supports Docker).
+#[derive(Clone)]
+pub struct LinuxHostTopology;
+
+#[async_trait]
+impl Docker for LinuxHostTopology {
+    async fn deploy_docker(&self) -> Result<String, String> {
+        // Real impl: Install/configure Docker on host.
+        Ok("LinuxHost Docker deployed".to_string())
+    }
+}
+
+/// Higher-Order Topology: Composes multiple sub-topologies (primary + replica).
+/// Automatically derives *all* capabilities of `T` with failover orchestration.
+/// 
+/// - If `T: PostgreSQL`, then `FailoverTopology<T>: PostgreSQL` (blanket impl).
+/// - Same for `Docker`, etc. No boilerplate!
+/// - Compile-time safe: Missing `T: Capability` → error.
+#[derive(Clone)]
+pub struct FailoverTopology<T> {
+    /// Primary sub-topology.
+    pub primary: T,
+    /// Replica sub-topology.
+    pub replica: T,
+}
+
+/// Blanket impl: Failover PostgreSQL if T provides PostgreSQL.
+/// Delegates reads to primary; deploys to both.
+#[async_trait]
+impl<T: PostgreSQL + Send + Sync + Clone> PostgreSQL for FailoverTopology<T> {
+    async fn deploy(&self, config: &PostgreSQLConfig) -> Result<String, String> {
+        // Orchestrate: Deploy primary first, then replica (e.g., via pg_basebackup).
+        let primary_result = self.primary.deploy(config).await?;
+        let replica_result = self.replica.deploy(config).await?;
+        Ok(format!("Failover PG deployed: {} | {}", primary_result, replica_result))
+    }
+
+    async fn get_replication_certs(&self, cluster_name: &str) -> Result<ReplicationCerts, String> {
+        // Delegate to primary (replica follows).
+        self.primary.get_replication_certs(cluster_name).await
+    }
+}
+
+/// Blanket impl: Failover Docker if T provides Docker.
+#[async_trait]
+impl<T: Docker + Send + Sync + Clone> Docker for FailoverTopology<T> {
+    async fn deploy_docker(&self) -> Result<String, String> {
+        // Orchestrate across primary + replica.
+        let primary_result = self.primary.deploy_docker().await?;
+        let replica_result = self.replica.deploy_docker().await?;
+        Ok(format!("Failover Docker deployed: {} | {}", primary_result, replica_result))
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    let config = PostgreSQLConfig;
+
+    println!("=== ✅ PostgreSQL Failover (K8sAnywhere supports PG) ===");
+    let pg_failover = FailoverTopology {
+        primary: K8sAnywhereTopology,
+        replica: K8sAnywhereTopology,
+    };
+    let result = pg_failover.deploy(&config).await.unwrap();
+    println!("Result: {}", result);
+
+    println!("\n=== ✅ Docker Failover (LinuxHost supports Docker) ===");
+    let docker_failover = FailoverTopology {
+        primary: LinuxHostTopology,
+        replica: LinuxHostTopology,
+    };
+    let result = docker_failover.deploy_docker().await.unwrap();
+    println!("Result: {}", result);
+
+    println!("\n=== ❌ Would fail to compile (K8sAnywhere !: Docker) ===");
+    // let invalid = FailoverTopology {
+    //     primary: K8sAnywhereTopology,
+    //     replica: K8sAnywhereTopology,
+    // };
+    // invalid.deploy_docker().await.unwrap(); // Error: `K8sAnywhereTopology: Docker` not satisfied!
+    // Very clear error message :
+    // error[E0599]: the method `deploy_docker` exists for struct `FailoverTopology<K8sAnywhereTopology>`, but its trait bounds were not satisfied
+    //   --> src/main.rs:90:9
+    //    |
+    //  4 | pub struct FailoverTopology<T> {
+    //    | ------------------------------ method `deploy_docker` not found for this struct because it doesn't satisfy `FailoverTopology<K8sAnywhereTopology>: Docker`
+    // ...
+    // 37 | struct K8sAnywhereTopology;
+    //    | -------------------------- doesn't satisfy `K8sAnywhereTopology: Docker`
+    // ...
+    // 90 | invalid.deploy_docker(); // `T: Docker` bound unsatisfied
+    //    |         ^^^^^^^^^^^^^ method cannot be called on `FailoverTopology<K8sAnywhereTopology>` due to unsatisfied trait bounds
+    //    |
+    // note: trait bound `K8sAnywhereTopology: Docker` was not satisfied
+    //   --> src/main.rs:61:9
+    //    |
+    // 61 | impl<T: Docker + Send + Sync> Docker for FailoverTopology<T> {
+    //    |         ^^^^^^                ------     -------------------
+    //    |         |
+    //    |         unsatisfied trait bound introduced here
+    // note: the trait `Docker` must be implemented
+}
+

adr/016-Harmony-Agent-And-Global-Mesh-For-Decentralized-Workload-Management.md

@@ -0,0 +1,90 @@
+# Architecture Decision Record: Global Orchestration Mesh & The Harmony Agent
+
+**Status:** Proposed
+**Date:** 2025-12-19
+
+## Context
+
+Harmony is designed to enable a truly decentralized infrastructure where independent clusters—owned by different organizations or running on diverse hardware—can collaborate reliably. This vision combines the decentralization of Web3 with the performance and capabilities of Web2.
+
+Currently, Harmony operates as a stateless CLI tool, invoked manually or via CI runners. While effective for deployment, this model presents a critical limitation: **a CLI cannot react to real-time events.**
+
+To achieve automated failover and dynamic workload management, we need a system that is "always on." Relying on manual intervention or scheduled CI jobs to recover from a cluster failure creates unacceptable latency and prevents us from scaling to thousands of nodes.
+
+Furthermore, we face a challenge in serving diverse workloads:
+*   **Financial workloads** require absolute consistency (CP - Consistency/Partition Tolerance).
+*   **AI/Inference workloads** require maximum availability (AP - Availability/Partition Tolerance).
+
+There are many more use cases, but those are the two extremes.
+
+We need a unified architecture that automates cluster coordination and supports both consistency models without requiring a complete re-architecture in the future.
+
+## Decision
+
+We propose a fundamental architectural evolution. It has been clear since the start of Harmony that it would be necessary to transition Harmony from a purely ephemeral CLI tool to a system that includes a persistent **Harmony Agent**. This Agent will connect to a **Global Orchestration Mesh** based on a strongly consistent protocol.
+
+The proposal consists of four key pillars:
+
+### 1. The Harmony Agent (New Component)
+We will develop a long-running process (Daemon/Agent) to be deployed alongside workloads.
+*   **Shift from CLI:** Unlike the CLI, which applies configuration and exits, the Agent maintains a persistent connection to the mesh.
+*   **Responsibility:** It actively monitors cluster health, participates in consensus, and executes lifecycle commands (start/stop/fence) instantly when the mesh dictates a state change.
+
+### 2. The Technology: NATS JetStream
+We will utilize **NATS JetStream** as the underlying transport and consensus layer for the Agent and the Mesh.
+*   **Why not raw Raft?** Implementing a raw Raft library requires building and maintaining the transport layer, log compaction, snapshotting, and peer discovery manually. NATS JetStream provides a battle-tested, distributed log and Key-Value store (based on Raft) out of the box, along with a high-performance pub/sub system for event propagation.
+*   **Role:** It will act as the "source of truth" for the cluster state.
+
+### 3. Strong Consistency at the Mesh Layer
+The mesh will operate with **Strong Consistency** by default.
+*   All critical cluster state changes (topology updates, lease acquisitions, leadership elections) will require consensus among the Agents.
+*   This ensures that in the event of a network partition, we have a mathematical guarantee of which side holds the valid state, preventing data corruption.
+
+### 4. Public UX: The `FailoverStrategy` Abstraction
+To keep the user experience stable and simple, we will expose the complexity of the mesh through a high-level configuration API, tentatively called `FailoverStrategy`.
+
+The user defines the *intent* in their config, and the Harmony Agent automates the *execution*:
+
+*   **`FailoverStrategy::AbsoluteConsistency`**:
+    *   *Use Case:* Banking, Transactional DBs.
+    *   *Behavior:* If the mesh detects a partition, the Agent on the minority side immediately halts workloads. No split-brain is ever allowed.
+*   **`FailoverStrategy::SplitBrainAllowed`**:
+    *   *Use Case:* LLM Inference, Stateless Web Servers.
+    *   *Behavior:* If a partition occurs, the Agent keeps workloads running to maximize uptime. State is reconciled when connectivity returns.
+
+## Rationale
+
+**The Necessity of an Agent**
+You cannot automate what you do not monitor. Moving to an Agent-based model is the only way to achieve sub-second reaction times to infrastructure failures. It transforms Harmony from a deployment tool into a self-healing platform.
+
+**Scaling & Decentralization**
+To allow independent clusters to collaborate, they need a shared language. A strongly consistent mesh allows Cluster A (Organization X) and Cluster B (Organization Y) to agree on workload placement without a central authority.
+
+**Why Strong Consistency First?**
+It is technically feasible to relax a strongly consistent system to allow for "Split Brain" behavior (AP) when the user requests it. However, it is nearly impossible to take an eventually consistent system and force it to be strongly consistent (CP) later. By starting with strict constraints, we cover the hardest use cases (Finance) immediately.
+
+**Future Topologies**
+While our immediate need is `FailoverTopology` (Multi-site), this architecture supports any future topology logic:
+*   **`CostTopology`**: Agents negotiate to route workloads to the cluster with the cheapest spot instances.
+*   **`HorizontalTopology`**: Spreading a single workload across 100 clusters for massive scale.
+*   **`GeoTopology`**: Ensuring data stays within specific legal jurisdictions.
+
+The mesh provides the *capability* (consensus and messaging); the topology provides the *logic*.
+
+## Consequences
+
+**Positive**
+*   **Automation:** Eliminates manual failover, enabling massive scale.
+*   **Reliability:** Guarantees data safety for critical workloads by default.
+*   **Flexibility:** A single codebase serves both high-frequency trading and AI inference.
+*   **Stability:** The public API remains abstract, allowing us to optimize the mesh internals without breaking user code.
+
+**Negative**
+*   **Deployment Complexity:** Users must now deploy and maintain a running service (the Agent) rather than just downloading a binary.
+*   **Engineering Complexity:** Integrating NATS JetStream and handling distributed state machines is significantly more complex than the current CLI logic.
+
+## Implementation Plan (Short Term)
+1.  **Agent Bootstrap:** Create the initial scaffold for the Harmony Agent (daemon).
+2.  **Mesh Integration:** Prototype NATS JetStream embedding within the Agent.
+3.  **Strategy Implementation:** Add `FailoverStrategy` to the configuration schema and implement the logic in the Agent to read and act on it.
+4.  **Migration:** Transition the current manual failover scripts into event-driven logic handled by the Agent.

adr/017-1-Nats-Clusters-Interconnection-Topology.md

@@ -0,0 +1,189 @@
+### 1. ADR 017-1: NATS Cluster Interconnection & Trust Topology
+
+# Architecture Decision Record: NATS Cluster Interconnection & Trust Topology
+
+**Status:** Proposed
+**Date:** 2026-01-12
+**Precedes:** [017-Staleness-Detection-for-Failover.md]
+
+## Context
+
+In ADR 017, we defined the failover mechanisms for the Harmony mesh. However, for a Primary (Site A) and a Replica (Site B) to communicate securely—or for the Global Mesh to function across disparate locations—we must establish a robust Transport Layer Security (TLS) strategy.
+
+Our primary deployment platform is OKD (Kubernetes). While OKD provides an internal `service-ca`, it is designed primarily for intra-cluster service-to-service communication. It lacks the flexibility required for:
+1.  **Public/External Gateway Identities:** NATS Gateways need to identify themselves via public DNS names or external IPs, not just internal `.svc` cluster domains.
+2.  **Cross-Cluster Trust:** We need a mechanism to allow Cluster A to trust Cluster B without sharing a single private root key.
+
+## Decision
+
+We will implement an **"Islands of Trust"** topology using **cert-manager** on OKD.
+
+### 1. Per-Cluster Certificate Authorities (CA)
+
+* We explicitly **reject** the use of a single "Supercluster CA" shared across all sites.
+    * Instead, every Harmony Cluster (Site A, Site B, etc.) will generate its own unique Self-Signed Root CA managed by `cert-manager` inside that cluster.
+*   **Lifecycle:** Root CAs will have a long duration (e.g., 10 years) to minimize rotation friction, while Leaf Certificates (NATS servers) will remain short-lived (e.g., 90 days) and rotate automatically.
+
+> Note : The decision to have a single CA for various workloads managed by Harmony on each deployment, or to have multiple CA for each service that requires interconnection is not made yet. This ADR leans towards one CA per service. This allows for maximum flexibility. But the direction might change and no clear decision has been made yet. The alternative of establishing that each cluster/harmony deployment has a single identity could make mTLS very simple between tenants.
+
+### 2. Trust Federation via Bundle Exchange
+
+To enable secure communication (mTLS) between clusters (e.g., for NATS Gateways or Leaf Nodes):
+
+*   **No Private Keys are shared.**
+*   We will aggregate the **Public CA Certificates** of all trusted clusters into a shared `ca-bundle.pem`.
+*   This bundle is distributed to the NATS configuration of every node.
+*   **Verification Logic:** When Site A connects to Site B, Site A verifies Site B's certificate against the bundle. Since Site B's CA public key is in the bundle, the connection is accepted.
+
+### 3. Tooling
+
+* We will use **cert-manager** (deployed via Operator on OKD) rather than OKD's built-in `service-ca`. This provides us with standard CRDs (`Issuer`, `Certificate`) to manage the lifecycle, rotation, and complex SANs (Subject Alternative Names) required for external connectivity.
+* Harmony will manage installation, configuration and bundle creation across all sites
+
+## Rationale
+
+**Security Blast Radius (The "Key Leak" Scenario)**
+If we used a single global CA and the private key for Site A was compromised (e.g., physical theft of a server from a basement), the attacker could impersonate *any* site in the global mesh.
+By using Per-Cluster CAs:
+*   If Site A is compromised, only Site A's identity is stolen.
+*   We can "evict" Site A from the mesh simply by removing Site A's Public CA from the `ca-bundle.pem` on the remaining healthy clusters and reloading. The attacker can no longer authenticate.
+
+**Decentralized Autonomy**
+This aligns with the "Humane Computing" vision. A local cluster owns its identity. It does not depend on a central authority to issue its certificates. It can function in isolation (offline) indefinitely without needing to "phone home" to renew credentials.
+
+## Consequences
+
+**Positive**
+*   **High Security:** Compromise of one node does not compromise the global mesh.
+*   **Flexibility:** Easier to integrate with third-party clusters or partners by simply adding their public CA to the bundle.
+*   **Standardization:** `cert-manager` is the industry standard, making the configuration portable to non-OKD K8s clusters if needed.
+
+**Negative**
+*   **Configuration Complexity:** We must manage a mechanism to distribute the `ca-bundle.pem` containing public keys to all sites. This should be automated (e.g., via a Harmony Agent) to ensure timely updates and revocation.
+*   **Revocation Latency:** Revoking a compromised cluster requires updating and reloading the bundle on all other clusters. This is slower than OCSP/CRL but acceptable for infrastructure-level trust if automation is in place.
+
+---
+
+# 2. Concrete overview of the process, how it can be implemented manually across multiple OKD clusters
+
+All of this will be automated via Harmony, but to understand correctly the process it is outlined in details here :
+
+## 1. Deploying and Configuring cert-manager on OKD
+
+While OKD has a built-in `service-ca` controller, it is "opinionated" and primarily signs certs for internal services (like `my-svc.my-namespace.svc`). It is **not suitable** for the Harmony Global Mesh because you cannot easily control the Subject Alternative Names (SANs) for external routes (e.g., `nats.site-a.nationtech.io`), nor can you easily export its CA to other clusters.
+
+**The Solution:** Use the **cert-manager Operator for Red Hat OpenShift**.
+
+### Step 1: Install the Operator
+1.  Log in to the OKD Web Console.
+2.  Navigate to **Operators** -> **OperatorHub**.
+3.  Search for **"cert-manager"**.
+4.  Choose the **"cert-manager Operator for Red Hat OpenShift"** (Red Hat provided) or the community version.
+5.  Click **Install**. Use the default settings (Namespace: `cert-manager-operator`).
+
+### Step 2: Create the "Island" CA (The Issuer)
+Once installed, you define your cluster's unique identity. Apply this YAML to your NATS namespace.
+
+```yaml
+# filepath: k8s/01-issuer.yaml
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: harmony-selfsigned-issuer
+  namespace: harmony-nats
+spec:
+  selfSigned: {}
+---
+# This generates the unique Root CA for THIS specific cluster
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: harmony-root-ca
+  namespace: harmony-nats
+spec:
+  isCA: true
+  commonName: "harmony-site-a-ca" # CHANGE THIS per cluster (e.g., site-b-ca)
+  duration: 87600h # 10 years
+  renewBefore: 2160h # 3 months before expiry
+  secretName: harmony-root-ca-secret
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  issuerRef:
+    name: harmony-selfsigned-issuer
+    kind: Issuer
+    group: cert-manager.io
+---
+# This Issuer uses the Root CA generated above to sign NATS certs
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: harmony-ca-issuer
+  namespace: harmony-nats
+spec:
+  ca:
+    secretName: harmony-root-ca-secret
+```
+
+### Step 3: Generate the NATS Server Certificate
+This certificate will be used by the NATS server. It includes both internal DNS names (for local clients) and external DNS names (for the global mesh).
+
+```yaml
+# filepath: k8s/02-nats-cert.yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: nats-server-cert
+  namespace: harmony-nats
+spec:
+  secretName: nats-server-tls
+  duration: 2160h # 90 days
+  renewBefore: 360h # 15 days
+  issuerRef:
+    name: harmony-ca-issuer
+    kind: Issuer
+  # CRITICAL: Define all names this server can be reached by
+  dnsNames:
+  - "nats"
+  - "nats.harmony-nats.svc"
+  - "nats.harmony-nats.svc.cluster.local"
+  - "*.nats.harmony-nats.svc.cluster.local"
+  - "nats-gateway.site-a.nationtech.io" # External Route for Mesh
+```
+
+## 2. Implementing the "Islands of Trust" (Trust Bundle)
+
+To make Site A and Site B talk, you need to exchange **Public Keys**.
+
+1.  **Extract Public CA from Site A:**
+    ```bash
+    oc get secret harmony-root-ca-secret -n harmony-nats -o jsonpath='{.data.ca\.crt}' | base64 -d > site-a.crt
+    ```
+2.  **Extract Public CA from Site B:**
+    ```bash
+    oc get secret harmony-root-ca-secret -n harmony-nats -o jsonpath='{.data.ca\.crt}' | base64 -d > site-b.crt
+    ```
+3.  **Create the Bundle:**
+    Combine them into one file.
+    ```bash
+    cat site-a.crt site-b.crt > ca-bundle.crt
+    ```
+4.  **Upload Bundle to Both Clusters:**
+    Create a ConfigMap or Secret in *both* clusters containing this combined bundle.
+    ```bash
+    oc create configmap nats-trust-bundle --from-file=ca.crt=ca-bundle.crt -n harmony-nats
+    ```
+5.  **Configure NATS:**
+    Mount this ConfigMap and point NATS to it.
+
+    ```conf
+    # nats.conf snippet
+    tls {
+      cert_file: "/etc/nats-certs/tls.crt"
+      key_file:  "/etc/nats-certs/tls.key"
+      # Point to the bundle containing BOTH Site A and Site B public CAs
+      ca_file:   "/etc/nats-trust/ca.crt"
+    }
+    ```
+
+This setup ensures that Site A can verify Site B's certificate (signed by `harmony-site-b-ca`) because Site B's CA is in Site A's trust store, and vice versa, without ever sharing the private keys that generated them.

adr/018-Template-Hydration-For-Workload-Deployment.md

@@ -0,0 +1,141 @@
+# Architecture Decision Record: Template Hydration for Kubernetes Manifest Generation
+
+Initial Author: Jean-Gabriel Gill-Couture & Sylvain Tremblay
+
+Initial Date: 2025-01-23
+
+Last Updated Date: 2025-01-23
+
+## Status
+
+Implemented
+
+## Context
+
+Harmony's philosophy is built on three guiding principles: Infrastructure as Resilient Code, Prove It Works — Before You Deploy, and One Unified Model. Our goal is to shift validation and verification as left as possible—ideally to compile time—rather than discovering errors at deploy time.
+
+After investigating a few approaches such as compile-checked Askama templates to generate Kubernetes manifests for Helm charts, we found again that this approach suffered from several fundamental limitations:
+
+*   **Late Validation:** Typos in template syntax or field names are only discovered at deployment time, not during compilation. A mistyped `metadata.name` won't surface until Helm attempts to render the template.
+*   **Brittle Maintenance:** Templates are string-based with limited IDE support. Refactoring requires grep-and-replace across YAML-like template files, risking subtle breakage.
+*   **Hard-to-Test Logic:** Testing template output requires mocking the template engine and comparing serialized strings rather than asserting against typed data structures.
+*   **No Type Safety:** There is no guarantee that the generated YAML will be valid Kubernetes resources without runtime validation.
+
+We also faced a strategic choice around Helm: use it as both *templating engine* and *packaging mechanism*, or decouple these concerns. While Helm's ecosystem integration (Harbor, ArgoCD, OCI registry support) is valuable, the Jinja-like templating is at odds with Harmony's "code-first" ethos.
+
+## Decision
+
+We will adopt the **Template Hydration Pattern**—constructing Kubernetes manifests programmatically using strongly-typed `kube-rs` objects, then serializing them to YAML files for packaging into Helm charts.
+
+Specifically:
+
+*   **Write strongly typed `k8s_openapi` Structs:** All Kubernetes resources (Deployment, Service, ConfigMap, etc.) will be constructed using the typed structs generated by `k8s_openapi`.
+*   **Direct Serialization to YAML:** Rather than rendering templates, we use `serde_yaml::to_string()` to serialize typed objects directly into YAML manifests. This way, YAML is only used as a data-transfer format and not a templating/programming language - which it is not.
+*   **Helm as Packaging-Only:** Helm's role is reduced to packaging pre-rendered templates into a tarball and pushing to OCI registries. No template rendering logic resides within Helm.
+*   **Ecosystem Preservation:** The generated Helm charts remain fully compatible with Harbor, ArgoCD, and any Helm-compatible tool—the only difference is that the `templates/` directory contains static YAML files.
+
+The implementation in `backend_app.rs` demonstrates this pattern:
+
+```rust
+let deployment = Deployment {
+    metadata: ObjectMeta {
+        name: Some(self.name.clone()),
+        labels: Some([("app.kubernetes.io/name".to_string(), self.name.clone())].into()),
+        ..Default::default()
+    },
+    spec: Some(DeploymentSpec { /* ... */ }),
+    ..Default::default()
+};
+
+let deployment_yaml = serde_yaml::to_string(&deployment)?;
+fs::write(templates_dir.join("deployment.yaml"), deployment_yaml)?;
+```
+
+## Rationale
+
+**Aligns with "Infrastructure as Resilient Code"**
+
+Harmony's first principle states that infrastructure should be treated like application code. By expressing Kubernetes manifests as Rust structs, we gain:
+
+*   **Refactorability:** Rename a label and the compiler catches all usages.
+*   **IDE Support:** Autocomplete for all Kubernetes API fields; documentation inline.
+*   **Code Navigation:** Jump to definition shows exactly where a value comes from.
+
+**Achieves "Prove It Works — Before You Deploy"**
+
+The compiler now validates that:
+
+*   All required fields are populated (Rust's `Option` type prevents missing fields).
+*   Field types match expectations (ports are integers, not strings).
+*   Enums contain valid values (e.g., `ServiceType::ClusterIP`).
+
+This moves what was runtime validation into compile-time checks, fulfilling the "shift left" promise.
+
+**Enables True Unit Testing**
+
+Developers can now write unit tests that assert directly against typed objects:
+
+```rust
+let deployment = create_deployment(&app);
+assert_eq!(deployment.spec.unwrap().replicas.unwrap(), 3);
+assert_eq!(deployment.metadata.name.unwrap(), "my-app");
+```
+
+No string parsing, no YAML serialization, no fragile assertions against rendered output.
+
+**Preserves Ecosystem Benefits**
+
+By generating standard Helm chart structures, Harmony retains compatibility with:
+
+*   **OCI Registries (Harbor, GHCR):** `helm push` works exactly as before.
+*   **ArgoCD:** Syncs and manages releases using the generated charts.
+*   **Existing Workflows:** Teams already consuming Helm charts see no change.
+
+The Helm tarball becomes a "dumb pipe" for transport, which is arguably its ideal role.
+
+## Consequences
+
+### Positive
+
+*   **Compile-Time Safety:** A broad class of errors (typos, missing fields, type mismatches) is now caught at build time.
+*   **Better Developer Experience:** IDE autocomplete, inline documentation, and refactor support significantly reduce the learning curve for Kubernetes manifests.
+*   **Testability:** Unit tests can validate manifest structure without integration or runtime checks.
+*   **Auditability:** The source-of-truth for manifests is now pure Rust—easier to review in pull requests than template logic scattered across files.
+*   **Future-Extensibility:** CustomResources (CRDs) can be supported via `kopium`-generated Rust types, maintaining the same strong typing.
+
+### Negative
+
+*   **API Schema Drift:** Kubernetes API changes require regenerating `k8s_openapi` types and updating code. A change in a struct field will cause the build to fail—intentionally, but still requiring the pipeline to be updated.
+*   **Verbosity:** Typed construction is more verbose than the equivalent template. Builder patterns or helper functions will be needed to keep code readable.
+*   **Learning Curve:** Contributors must understand both the Kubernetes resource spec *and* the Rust type system, rather than just YAML.
+*   **Debugging Shift:** When debugging generated YAML, you now trace through Rust code rather than template files—more precise but different mental model.
+
+## Alternatives Considered
+
+### 1. Enhance Askama with Compile-Time Validation
+*Pros:* Stay within familiar templating paradigm; minimal code changes.
+*Cons:* Rust's type system cannot fully express Kubernetes schema validation without significant macro boilerplate. Errors would still surface at template evaluation time, not compilation.
+
+### 2. Use Helm SDK Programmatically (Go)
+*Pros:* Direct access to Helm's template engine; no YAML serialization step.
+*Cons:* Would introduce a second language (Go) into a Rust codebase, increasing cognitive load and compilation complexity. No improvement in compile-time safety.
+
+### 3. Raw YAML String Templating (Manual)
+*Pros:* Maximum control; no external dependencies.
+*Cons:* Even more error-prone than Askama; no structure validation; string concatenation errors abound.
+
+### 4. Use Kustomize for All Manifests
+*Pros:* Declarative overlays; standard tool.
+*Cons:* Kustomize is itself a layer over YAML templates with its own DSL. It does not provide compile-time type safety and would require externalizing manifest management outside Harmony's codebase.
+
+__Note that this template hydration architecture still allows to override templates with tools like kustomize when required__
+
+## Additional Notes
+
+**Scalability to Future Topologies**
+
+The Template Hydration pattern enables future Harmony architectures to generate manifests dynamically based on topology context. For example, a `CostTopology` might adjust resource requests based on cluster pricing, manipulating the typed `Deployment::spec` directly before serialization.
+
+**Implementation Status**
+
+As of this writing, the pattern is implemented for `BackendApp` deployments (`backend_app.rs`). The next phase is to extend this pattern across all application modules (`webapp.rs`, etc.) and to standardize on this approach for any new implementations.

adr/019-Network-bond-setup.md

@@ -0,0 +1,65 @@
+# Architecture Decision Record: Network Bonding Configuration via External Automation
+
+Initial Author: Jean-Gabriel Gill-Couture & Sylvain Tremblay
+
+Initial Date: 2026-02-13
+
+Last Updated Date: 2026-02-13
+
+## Status
+
+Accepted
+
+## Context
+
+We need to configure LACP bonds on 10GbE interfaces across all worker nodes in the OpenShift cluster. A significant challenge is that interface names (e.g., `enp1s0f0` vs `ens1f0`) vary across different hardware nodes.
+
+The standard OpenShift mechanism (MachineConfig) applies identical configurations to all nodes in a MachineConfigPool. Since the interface names differ, a single static MachineConfig cannot target specific physical devices across the entire cluster without complex workarounds.
+
+## Decision
+
+We will use the existing "Harmony" automation tool to generate and apply host-specific NetworkManager configuration files directly to the nodes.
+
+1.  Harmony will generate the specific `.nmconnection` files for the bond and slaves based on its inventory of interface names.
+2.  Files will be pushed to `/etc/NetworkManager/system-connections/` on each node.
+3.  Configuration will be applied via `nmcli` reload or a node reboot.
+
+## Rationale
+
+*   **Inventory Awareness:** Harmony already possesses the specific interface mapping data for each host.
+*   **Persistence:** Fedora CoreOS/SCOS allows writing to `/etc`, and these files persist across reboots and OS upgrades (rpm-ostree updates).
+*   **Avoids Complexity:** This approach avoids the operational overhead of creating unique MachineConfigPools for every single host or hardware variant.
+*   **Safety:** Unlike wildcard matching, this ensures explicit interface selection, preventing accidental bonding of reserved interfaces (e.g., future separation of Ceph storage traffic).
+
+## Consequences
+
+**Pros:**
+*   Precise, per-host configuration without polluting the Kubernetes API with hundreds of MachineConfigs.
+*   Standard Linux networking behavior; easy to debug locally.
+*   Prevents accidental interface capture (unlike wildcards).
+
+**Cons:**
+*   **Loss of Declarative K8s State:** The network config is not managed by the Machine Config Operator (MCO).
+*   **Node Replacement Friction:** Newly provisioned nodes (replacements) will boot with default config. Harmony must be run against new nodes manually or via a hook before they can fully join the cluster workload.
+
+## Alternatives considered
+
+1.  **Wildcard Matching in NetworkManager (e.g., `interface-name=enp*`):**
+    *   *Pros:* Single MachineConfig for the whole cluster.
+    *   *Cons:* Rejected because it is too broad. It risks capturing interfaces intended for other purposes (e.g., splitting storage and cluster networks later).
+
+2.  **"Kitchen Sink" Configuration:**
+    *   *Pros:* Single file listing every possible interface name as a slave.
+    *   *Cons:* "Dirty" configuration; results in many inactive connections on every host; brittle if new naming schemes appear.
+
+3.  **Per-Host MachineConfig:**
+    *   *Pros:* Fully declarative within OpenShift.
+    *   *Cons:* Requires a unique `MachineConfigPool` per host, which is an anti-pattern and unmaintainable at scale.
+
+4.  **On-boot Generation Script:**
+    *   *Pros:* Dynamic detection.
+    *   *Cons:* Increases boot complexity; harder to debug if the script fails during startup.
+
+## Additional Notes
+
+While `/etc` is writable and persistent on CoreOS, this configuration falls outside the "Day 1" Ignition process. Operational runbooks must be updated to ensure Harmony runs on any node replacement events.

adr/agent_discovery/mdns/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "mdns"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+mdns-sd = "0.14"
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+dmidecode = "0.2" # For getting the motherboard ID on the agent
+log.workspace=true
+env_logger.workspace=true
+clap = { version = "4.5.46", features = ["derive"] }
+get_if_addrs = "0.5.3"
+local-ip-address = "0.6.5"

adr/agent_discovery/mdns/src/advertise.rs

@@ -0,0 +1,60 @@
+// harmony-agent/src/main.rs
+
+use log::info;
+use mdns_sd::{ServiceDaemon, ServiceInfo};
+use std::collections::HashMap;
+
+use crate::SERVICE_TYPE;
+
+// The service we are advertising.
+const SERVICE_PORT: u16 = 43210; // A port for the service. It needs one, even if unused.
+
+pub async fn advertise() {
+    info!("Starting Harmony Agent...");
+
+    // Get a unique ID for this machine.
+    let motherboard_id = "some motherboard id";
+    let instance_name = format!("harmony-agent-{}", motherboard_id);
+    info!("This agent's instance name: {}", instance_name);
+    info!("Advertising with ID: {}", motherboard_id);
+
+    // Create a new mDNS daemon.
+    let mdns = ServiceDaemon::new().expect("Failed to create mDNS daemon");
+
+    // Create a TXT record HashMap to hold our metadata.
+    let mut properties = HashMap::new();
+    properties.insert("id".to_string(), motherboard_id.to_string());
+    properties.insert("version".to_string(), "1.0".to_string());
+
+    // Create the service information.
+    // The instance name should be unique on the network.
+    let local_ip = local_ip_address::local_ip().unwrap();
+    let service_info = ServiceInfo::new(
+        SERVICE_TYPE,
+        &instance_name,
+        "harmony-host.local.", // A hostname for the service
+        local_ip,
+        // "0.0.0.0",
+        SERVICE_PORT,
+        Some(properties),
+    )
+    .expect("Failed to create service info");
+
+    // Register our service with the daemon.
+    mdns.register(service_info)
+        .expect("Failed to register service");
+
+    info!(
+        "Service '{}' registered and now being advertised.",
+        instance_name
+    );
+    info!("Agent is running. Press Ctrl+C to exit.");
+
+    for iface in get_if_addrs::get_if_addrs().unwrap() {
+        println!("{:#?}", iface);
+    }
+
+    // Keep the agent running indefinitely.
+    tokio::signal::ctrl_c().await.unwrap();
+    info!("Shutting down agent.");
+}

adr/agent_discovery/mdns/src/discover.rs

@@ -0,0 +1,109 @@
+use mdns_sd::{ServiceDaemon, ServiceEvent};
+
+use crate::SERVICE_TYPE;
+
+pub async fn discover() {
+    println!("Starting Harmony Master and browsing for agents...");
+
+    // Create a new mDNS daemon.
+    let mdns = ServiceDaemon::new().expect("Failed to create mDNS daemon");
+
+    // Start browsing for the service type.
+    // The receiver will be a stream of events.
+    let receiver = mdns.browse(SERVICE_TYPE).expect("Failed to browse");
+
+    println!(
+        "Listening for mDNS events for '{}'. Press Ctrl+C to exit.",
+        SERVICE_TYPE
+    );
+
+    std::thread::spawn(move || {
+        while let Ok(event) = receiver.recv() {
+            match event {
+                ServiceEvent::ServiceData(resolved) => {
+                    println!("Resolved a new service: {}", resolved.fullname);
+                }
+                other_event => {
+                    println!("Received other event: {:?}", &other_event);
+                }
+            }
+        }
+    });
+
+    // Gracefully shutdown the daemon.
+    std::thread::sleep(std::time::Duration::from_secs(1000000));
+    mdns.shutdown().unwrap();
+
+    // Process events as they come in.
+    // while let Ok(event) = receiver.recv_async().await {
+    //     debug!("Received event {event:?}");
+    //     // match event {
+    //     //     ServiceEvent::ServiceFound(svc_type, fullname) => {
+    //     //         println!("\n--- Agent Discovered ---");
+    //     //         println!("  Service Name: {}", fullname());
+    //     //         // You can now resolve this service to get its IP, port, and TXT records
+    //     //         // The resolve operation is a separate network call.
+    //     //         let receiver = mdns.browse(info.get_fullname()).unwrap();
+    //     //         if let Ok(resolve_event) = receiver.recv_timeout(Duration::from_secs(2)) {
+    //     //              if let ServiceEvent::ServiceResolved(info) = resolve_event {
+    //     //                 let ip = info.get_addresses().iter().next().unwrap();
+    //     //                 let port = info.get_port();
+    //     //                 let motherboard_id = info.get_property("id").map_or("N/A", |v| v.val_str());
+    //     //
+    //     //                 println!("  IP: {}:{}", ip, port);
+    //     //                 println!("  Motherboard ID: {}", motherboard_id);
+    //     //                 println!("------------------------");
+    //     //
+    //     //                 // TODO: Add this agent to your central list of discovered hosts.
+    //     //              }
+    //     //         } else {
+    //     //             println!("Could not resolve service '{}' in time.", info.get_fullname());
+    //     //         }
+    //     //     }
+    //     //     ServiceEvent::ServiceRemoved(info) => {
+    //     //         println!("\n--- Agent Removed ---");
+    //     //         println!("  Service Name: {}", info.get_fullname());
+    //     //         println!("---------------------");
+    //     //         // TODO: Remove this agent from your list.
+    //     //     }
+    //     //     _ => {
+    //     //         // We don't care about other event types for this example
+    //     //     }
+    //     // }
+    // }
+}
+
+async fn _discover_example() {
+    use mdns_sd::{ServiceDaemon, ServiceEvent};
+
+    // Create a daemon
+    let mdns = ServiceDaemon::new().expect("Failed to create daemon");
+
+    // Use recently added `ServiceEvent::ServiceData`.
+    mdns.use_service_data(true)
+        .expect("Failed to use ServiceData");
+
+    // Browse for a service type.
+    let service_type = "_mdns-sd-my-test._udp.local.";
+    let receiver = mdns.browse(service_type).expect("Failed to browse");
+
+    // Receive the browse events in sync or async. Here is
+    // an example of using a thread. Users can call `receiver.recv_async().await`
+    // if running in async environment.
+    std::thread::spawn(move || {
+        while let Ok(event) = receiver.recv() {
+            match event {
+                ServiceEvent::ServiceData(resolved) => {
+                    println!("Resolved a new service: {}", resolved.fullname);
+                }
+                other_event => {
+                    println!("Received other event: {:?}", &other_event);
+                }
+            }
+        }
+    });
+
+    // Gracefully shutdown the daemon.
+    std::thread::sleep(std::time::Duration::from_secs(1));
+    mdns.shutdown().unwrap();
+}

adr/agent_discovery/mdns/src/main.rs

@@ -0,0 +1,31 @@
+use clap::{Parser, ValueEnum};
+
+mod advertise;
+mod discover;
+
+#[derive(Parser, Debug)]
+#[command(version, about, long_about = None)]
+struct Args {
+    #[arg(value_enum)]
+    profile: Profiles,
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]
+enum Profiles {
+    Advertise,
+    Discover,
+}
+
+// The service type we are looking for.
+const SERVICE_TYPE: &str = "_harmony._tcp.local.";
+
+#[tokio::main]
+async fn main() {
+    env_logger::init();
+    let args = Args::parse();
+
+    match args.profile {
+        Profiles::Advertise => advertise::advertise().await,
+        Profiles::Discover => discover::discover().await,
+    }
+}

brocade/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "brocade"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+async-trait.workspace = true
+harmony_types = { path = "../harmony_types" }
+russh.workspace = true
+russh-keys.workspace = true
+tokio.workspace = true
+log.workspace = true
+env_logger.workspace = true
+regex = "1.11.3"
+harmony_secret = { path = "../harmony_secret" }
+serde.workspace = true
+schemars = "0.8"

brocade/examples/main.rs

@@ -0,0 +1,75 @@
+use std::net::{IpAddr, Ipv4Addr};
+
+use brocade::{BrocadeOptions, ssh};
+use harmony_secret::{Secret, SecretManager};
+use harmony_types::switch::PortLocation;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[derive(Secret, Clone, Debug, JsonSchema, Serialize, Deserialize)]
+struct BrocadeSwitchAuth {
+    username: String,
+    password: String,
+}
+
+#[tokio::main]
+async fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    // let ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 250)); // old brocade @ ianlet
+    let ip = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)); // brocade @ sto1
+    // let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 4, 11)); // brocade @ st
+    let switch_addresses = vec![ip];
+
+    let config = SecretManager::get_or_prompt::<BrocadeSwitchAuth>()
+        .await
+        .unwrap();
+
+    let brocade = brocade::init(
+        &switch_addresses,
+        &config.username,
+        &config.password,
+        &BrocadeOptions {
+            dry_run: true,
+            ssh: ssh::SshOptions {
+                port: 2222,
+                ..Default::default()
+            },
+            ..Default::default()
+        },
+    )
+    .await
+    .expect("Brocade client failed to connect");
+
+    let entries = brocade.get_stack_topology().await.unwrap();
+    println!("Stack topology: {entries:#?}");
+
+    let entries = brocade.get_interfaces().await.unwrap();
+    println!("Interfaces: {entries:#?}");
+
+    let version = brocade.version().await.unwrap();
+    println!("Version: {version:?}");
+
+    println!("--------------");
+    let mac_adddresses = brocade.get_mac_address_table().await.unwrap();
+    println!("VLAN\tMAC\t\t\tPORT");
+    for mac in mac_adddresses {
+        println!("{}\t{}\t{}", mac.vlan, mac.mac_address, mac.port);
+    }
+
+    println!("--------------");
+    todo!();
+    let channel_name = "1";
+    brocade.clear_port_channel(channel_name).await.unwrap();
+
+    println!("--------------");
+    let channel_id = brocade.find_available_channel_id().await.unwrap();
+
+    println!("--------------");
+    let channel_name = "HARMONY_LAG";
+    let ports = [PortLocation(2, 0, 35)];
+    brocade
+        .create_port_channel(channel_id, channel_name, &ports)
+        .await
+        .unwrap();
+}

brocade/src/fast_iron.rs

@@ -0,0 +1,229 @@
+use super::BrocadeClient;
+use crate::{
+    BrocadeInfo, Error, ExecutionMode, InterSwitchLink, InterfaceInfo, MacAddressEntry,
+    PortChannelId, PortOperatingMode, SecurityLevel, parse_brocade_mac_address,
+    shell::BrocadeShell,
+};
+
+use async_trait::async_trait;
+use harmony_types::switch::{PortDeclaration, PortLocation};
+use log::{debug, info};
+use regex::Regex;
+use std::{collections::HashSet, str::FromStr};
+
+#[derive(Debug)]
+pub struct FastIronClient {
+    shell: BrocadeShell,
+    version: BrocadeInfo,
+}
+
+impl FastIronClient {
+    pub fn init(mut shell: BrocadeShell, version_info: BrocadeInfo) -> Self {
+        shell.before_all(vec!["skip-page-display".into()]);
+        shell.after_all(vec!["page".into()]);
+
+        Self {
+            shell,
+            version: version_info,
+        }
+    }
+
+    fn parse_mac_entry(&self, line: &str) -> Option<Result<MacAddressEntry, Error>> {
+        debug!("[Brocade] Parsing mac address entry: {line}");
+        let parts: Vec<&str> = line.split_whitespace().collect();
+        if parts.len() < 3 {
+            return None;
+        }
+
+        let (vlan, mac_address, port) = match parts.len() {
+            3 => (
+                u16::from_str(parts[0]).ok()?,
+                parse_brocade_mac_address(parts[1]).ok()?,
+                parts[2].to_string(),
+            ),
+            _ => (
+                1,
+                parse_brocade_mac_address(parts[0]).ok()?,
+                parts[1].to_string(),
+            ),
+        };
+
+        let port =
+            PortDeclaration::parse(&port).map_err(|e| Error::UnexpectedError(format!("{e}")));
+
+        match port {
+            Ok(p) => Some(Ok(MacAddressEntry {
+                vlan,
+                mac_address,
+                port: p,
+            })),
+            Err(e) => Some(Err(e)),
+        }
+    }
+
+    fn parse_stack_port_entry(&self, line: &str) -> Option<Result<InterSwitchLink, Error>> {
+        debug!("[Brocade] Parsing stack port entry: {line}");
+        let parts: Vec<&str> = line.split_whitespace().collect();
+        if parts.len() < 10 {
+            return None;
+        }
+
+        let local_port = PortLocation::from_str(parts[0]).ok()?;
+
+        Some(Ok(InterSwitchLink {
+            local_port,
+            remote_port: None,
+        }))
+    }
+
+    fn build_port_channel_commands(
+        &self,
+        channel_id: PortChannelId,
+        channel_name: &str,
+        ports: &[PortLocation],
+    ) -> Vec<String> {
+        let mut commands = vec![
+            "configure terminal".to_string(),
+            format!("lag {channel_name} static id {channel_id}"),
+        ];
+
+        for port in ports {
+            commands.push(format!("ports ethernet {port}"));
+        }
+
+        commands.push(format!("primary-port {}", ports[0]));
+        commands.push("deploy".into());
+        commands.push("exit".into());
+        commands.push("write memory".into());
+        commands.push("exit".into());
+
+        commands
+    }
+}
+
+#[async_trait]
+impl BrocadeClient for FastIronClient {
+    async fn version(&self) -> Result<BrocadeInfo, Error> {
+        Ok(self.version.clone())
+    }
+
+    async fn get_mac_address_table(&self) -> Result<Vec<MacAddressEntry>, Error> {
+        info!("[Brocade] Showing MAC address table...");
+
+        let output = self
+            .shell
+            .run_command("show mac-address", ExecutionMode::Regular)
+            .await?;
+
+        output
+            .lines()
+            .skip(2)
+            .filter_map(|line| self.parse_mac_entry(line))
+            .collect()
+    }
+
+    async fn get_stack_topology(&self) -> Result<Vec<InterSwitchLink>, Error> {
+        let output = self
+            .shell
+            .run_command("show interface stack-ports", crate::ExecutionMode::Regular)
+            .await?;
+
+        output
+            .lines()
+            .skip(1)
+            .filter_map(|line| self.parse_stack_port_entry(line))
+            .collect()
+    }
+
+    async fn get_interfaces(&self) -> Result<Vec<InterfaceInfo>, Error> {
+        todo!()
+    }
+
+    async fn configure_interfaces(
+        &self,
+        _interfaces: &Vec<(String, PortOperatingMode)>,
+    ) -> Result<(), Error> {
+        todo!()
+    }
+
+    async fn find_available_channel_id(&self) -> Result<PortChannelId, Error> {
+        info!("[Brocade] Finding next available channel id...");
+
+        let output = self
+            .shell
+            .run_command("show lag", ExecutionMode::Regular)
+            .await?;
+        let re = Regex::new(r"=== LAG .* ID\s+(\d+)").expect("Invalid regex");
+
+        let used_ids: HashSet<u8> = output
+            .lines()
+            .filter_map(|line| {
+                re.captures(line)
+                    .and_then(|c| c.get(1))
+                    .and_then(|id_match| id_match.as_str().parse().ok())
+            })
+            .collect();
+
+        let mut next_id: u8 = 1;
+        loop {
+            if !used_ids.contains(&next_id) {
+                break;
+            }
+            next_id += 1;
+        }
+
+        info!("[Brocade] Found channel id: {next_id}");
+        Ok(next_id)
+    }
+
+    async fn create_port_channel(
+        &self,
+        channel_id: PortChannelId,
+        channel_name: &str,
+        ports: &[PortLocation],
+    ) -> Result<(), Error> {
+        info!(
+            "[Brocade] Configuring port-channel '{channel_name} {channel_id}' with ports: {ports:?}"
+        );
+
+        let commands = self.build_port_channel_commands(channel_id, channel_name, ports);
+        self.shell
+            .run_commands(commands, ExecutionMode::Privileged)
+            .await?;
+
+        info!("[Brocade] Port-channel '{channel_name}' configured.");
+        Ok(())
+    }
+
+    async fn clear_port_channel(&self, channel_name: &str) -> Result<(), Error> {
+        info!("[Brocade] Clearing port-channel: {channel_name}");
+
+        let commands = vec![
+            "configure terminal".to_string(),
+            format!("no lag {channel_name}"),
+            "write memory".to_string(),
+        ];
+        self.shell
+            .run_commands(commands, ExecutionMode::Privileged)
+            .await?;
+
+        info!("[Brocade] Port-channel '{channel_name}' cleared.");
+        Ok(())
+    }
+
+    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error> {
+        let commands = vec![
+            "configure terminal".into(),
+            "snmp-server view ALL 1 included".into(),
+            "snmp-server group public v3 priv read ALL".into(),
+            format!(
+                "snmp-server user {user_name} groupname public auth md5 auth-password {auth} priv des priv-password {des}"
+            ),
+            "exit".into(),
+        ];
+        self.shell
+            .run_commands(commands, ExecutionMode::Regular)
+            .await?;
+        Ok(())
+    }
+}

brocade/src/lib.rs

@@ -0,0 +1,352 @@
+use std::net::IpAddr;
+use std::{
+    fmt::{self, Display},
+    time::Duration,
+};
+
+use crate::network_operating_system::NetworkOperatingSystemClient;
+use crate::{
+    fast_iron::FastIronClient,
+    shell::{BrocadeSession, BrocadeShell},
+};
+
+use async_trait::async_trait;
+use harmony_types::net::MacAddress;
+use harmony_types::switch::{PortDeclaration, PortLocation};
+use regex::Regex;
+use serde::Serialize;
+
+mod fast_iron;
+mod network_operating_system;
+mod shell;
+pub mod ssh;
+
+#[derive(Default, Clone, Debug)]
+pub struct BrocadeOptions {
+    pub dry_run: bool,
+    pub ssh: ssh::SshOptions,
+    pub timeouts: TimeoutConfig,
+}
+
+#[derive(Clone, Debug)]
+pub struct TimeoutConfig {
+    pub shell_ready: Duration,
+    pub command_execution: Duration,
+    pub command_output: Duration,
+    pub cleanup: Duration,
+    pub message_wait: Duration,
+}
+
+impl Default for TimeoutConfig {
+    fn default() -> Self {
+        Self {
+            shell_ready: Duration::from_secs(10),
+            command_execution: Duration::from_secs(60), // Commands like `deploy` (for a LAG) can take a while
+            command_output: Duration::from_secs(5), // Delay to start logging "waiting for command output"
+            cleanup: Duration::from_secs(10),
+            message_wait: Duration::from_millis(500),
+        }
+    }
+}
+
+enum ExecutionMode {
+    Regular,
+    Privileged,
+}
+
+#[derive(Clone, Debug)]
+pub struct BrocadeInfo {
+    os: BrocadeOs,
+    _version: String,
+}
+
+#[derive(Clone, Debug)]
+pub enum BrocadeOs {
+    NetworkOperatingSystem,
+    FastIron,
+    Unknown,
+}
+
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone)]
+pub struct MacAddressEntry {
+    pub vlan: u16,
+    pub mac_address: MacAddress,
+    pub port: PortDeclaration,
+}
+
+pub type PortChannelId = u8;
+
+/// Represents a single physical or logical link connecting two switches within a stack or fabric.
+///
+/// This structure provides a standardized view of the topology regardless of the
+/// underlying Brocade OS configuration (stacking vs. fabric).
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct InterSwitchLink {
+    /// The local port on the switch where the topology command was run.
+    pub local_port: PortLocation,
+    /// The port on the directly connected neighboring switch.
+    pub remote_port: Option<PortLocation>,
+}
+
+/// Represents the key running configuration status of a single switch interface.
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct InterfaceInfo {
+    /// The full configuration name (e.g., "TenGigabitEthernet 1/0/1", "FortyGigabitEthernet 2/0/2").
+    pub name: String,
+    /// The physical location of the interface.
+    pub port_location: PortLocation,
+    /// The parsed type and name prefix of the interface.
+    pub interface_type: InterfaceType,
+    /// The primary configuration mode defining the interface's behavior (L2, L3, Fabric).
+    pub operating_mode: Option<PortOperatingMode>,
+    /// Indicates the current state of the interface.
+    pub status: InterfaceStatus,
+}
+
+/// Categorizes the functional type of a switch interface.
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub enum InterfaceType {
+    /// Physical or virtual Ethernet interface (e.g., TenGigabitEthernet, FortyGigabitEthernet).
+    Ethernet(String),
+}
+
+impl fmt::Display for InterfaceType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InterfaceType::Ethernet(name) => write!(f, "{name}"),
+        }
+    }
+}
+
+/// Defines the primary configuration mode of a switch interface, representing mutually exclusive roles.
+#[derive(Debug, PartialEq, Eq, Clone, Serialize)]
+pub enum PortOperatingMode {
+    /// The interface is explicitly configured for Brocade fabric roles (ISL or Trunk enabled).
+    Fabric,
+    /// The interface is configured for standard Layer 2 switching as Trunk port (`switchport mode trunk`).
+    Trunk,
+    /// The interface is configured for standard Layer 2 switching as Access port (`switchport` without trunk mode).
+    Access,
+}
+
+/// Defines the possible status of an interface.
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub enum InterfaceStatus {
+    /// The interface is connected.
+    Connected,
+    /// The interface is not connected and is not expected to be.
+    NotConnected,
+    /// The interface is not connected but is expected to be (configured with `no shutdown`).
+    SfpAbsent,
+}
+
+pub async fn init(
+    ip_addresses: &[IpAddr],
+    username: &str,
+    password: &str,
+    options: &BrocadeOptions,
+) -> Result<Box<dyn BrocadeClient + Send + Sync>, Error> {
+    let shell = BrocadeShell::init(ip_addresses, username, password, options).await?;
+
+    let version_info = shell
+        .with_session(ExecutionMode::Regular, |session| {
+            Box::pin(get_brocade_info(session))
+        })
+        .await?;
+
+    Ok(match version_info.os {
+        BrocadeOs::FastIron => Box::new(FastIronClient::init(shell, version_info)),
+        BrocadeOs::NetworkOperatingSystem => {
+            Box::new(NetworkOperatingSystemClient::init(shell, version_info))
+        }
+        BrocadeOs::Unknown => todo!(),
+    })
+}
+
+#[async_trait]
+pub trait BrocadeClient: std::fmt::Debug {
+    /// Retrieves the operating system and version details from the connected Brocade switch.
+    ///
+    /// This is typically the first call made after establishing a connection to determine
+    /// the switch OS family (e.g., FastIron, NOS) for feature compatibility.
+    ///
+    /// # Returns
+    ///
+    /// A `BrocadeInfo` structure containing parsed OS type and version string.
+    async fn version(&self) -> Result<BrocadeInfo, Error>;
+
+    /// Retrieves the dynamically learned MAC address table from the switch.
+    ///
+    /// This is crucial for discovering where specific network endpoints (MAC addresses)
+    /// are currently located on the physical ports.
+    ///
+    /// # Returns
+    ///
+    /// A vector of `MacAddressEntry`, where each entry typically contains VLAN, MAC address,
+    /// and the associated port name/index.
+    async fn get_mac_address_table(&self) -> Result<Vec<MacAddressEntry>, Error>;
+
+    /// Derives the physical connections used to link multiple switches together
+    /// to form a single logical entity (stack, fabric, etc.).
+    ///
+    /// This abstracts the underlying configuration (e.g., stack ports, fabric ports)
+    /// to return a standardized view of the topology.
+    ///
+    /// # Returns
+    ///
+    /// A vector of `InterSwitchLink` structs detailing which ports are used for stacking/fabric.
+    /// If the switch is not stacked, returns an empty vector.
+    async fn get_stack_topology(&self) -> Result<Vec<InterSwitchLink>, Error>;
+
+    /// Retrieves the status for all interfaces
+    ///
+    /// # Returns
+    ///
+    /// A vector of `InterfaceInfo` structures.
+    async fn get_interfaces(&self) -> Result<Vec<InterfaceInfo>, Error>;
+
+    /// Configures a set of interfaces to be operated with a specified mode (access ports, ISL, etc.).
+    async fn configure_interfaces(
+        &self,
+        interfaces: &Vec<(String, PortOperatingMode)>,
+    ) -> Result<(), Error>;
+
+    /// Scans the existing configuration to find the next available (unused)
+    /// Port-Channel ID (`lag` or `trunk`) for assignment.
+    ///
+    /// # Returns
+    ///
+    /// The smallest, unassigned `PortChannelId` within the supported range.
+    async fn find_available_channel_id(&self) -> Result<PortChannelId, Error>;
+
+    /// Creates and configures a new Port-Channel (Link Aggregation Group or LAG)
+    /// using the specified channel ID and ports.
+    ///
+    /// The resulting configuration must be persistent (saved to startup-config).
+    /// Assumes a static LAG configuration mode unless specified otherwise by the implementation.
+    ///
+    /// # Parameters
+    ///
+    /// * `channel_id`: The ID (e.g., 1-128) for the logical port channel.
+    /// * `channel_name`: A descriptive name for the LAG (used in configuration context).
+    /// * `ports`: A slice of `PortLocation` structs defining the physical member ports.
+    async fn create_port_channel(
+        &self,
+        channel_id: PortChannelId,
+        channel_name: &str,
+        ports: &[PortLocation],
+    ) -> Result<(), Error>;
+
+    /// Enables Simple Network Management Protocol (SNMP) server for switch
+    ///
+    /// # Parameters
+    ///
+    ///  * `user_name`: The user name for the snmp server
+    ///  * `auth`: The password for authentication process for verifying the identity of a device
+    ///  * `des`: The Data Encryption Standard algorithm key
+    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error>;
+
+    /// Removes all configuration associated with the specified Port-Channel name.
+    ///
+    /// This operation should be idempotent; attempting to clear a non-existent
+    /// channel should succeed (or return a benign error).
+    ///
+    /// # Parameters
+    ///
+    /// * `channel_name`: The name of the Port-Channel (LAG) to delete.
+    ///
+    async fn clear_port_channel(&self, channel_name: &str) -> Result<(), Error>;
+}
+
+async fn get_brocade_info(session: &mut BrocadeSession) -> Result<BrocadeInfo, Error> {
+    let output = session.run_command("show version").await?;
+
+    if output.contains("Network Operating System") {
+        let re = Regex::new(r"Network Operating System Version:\s*(?P<version>[a-zA-Z0-9.\-]+)")
+            .expect("Invalid regex");
+        let version = re
+            .captures(&output)
+            .and_then(|cap| cap.name("version"))
+            .map(|m| m.as_str().to_string())
+            .unwrap_or_default();
+
+        return Ok(BrocadeInfo {
+            os: BrocadeOs::NetworkOperatingSystem,
+            _version: version,
+        });
+    } else if output.contains("ICX") {
+        let re = Regex::new(r"(?m)^\s*SW: Version\s*(?P<version>[a-zA-Z0-9.\-]+)")
+            .expect("Invalid regex");
+        let version = re
+            .captures(&output)
+            .and_then(|cap| cap.name("version"))
+            .map(|m| m.as_str().to_string())
+            .unwrap_or_default();
+
+        return Ok(BrocadeInfo {
+            os: BrocadeOs::FastIron,
+            _version: version,
+        });
+    }
+
+    Err(Error::UnexpectedError("Unknown Brocade OS version".into()))
+}
+
+fn parse_brocade_mac_address(value: &str) -> Result<MacAddress, String> {
+    let cleaned_mac = value.replace('.', "");
+
+    if cleaned_mac.len() != 12 {
+        return Err(format!("Invalid MAC address: {value}"));
+    }
+
+    let mut bytes = [0u8; 6];
+    for (i, pair) in cleaned_mac.as_bytes().chunks(2).enumerate() {
+        let byte_str = std::str::from_utf8(pair).map_err(|_| "Invalid UTF-8")?;
+        bytes[i] =
+            u8::from_str_radix(byte_str, 16).map_err(|_| format!("Invalid hex in MAC: {value}"))?;
+    }
+
+    Ok(MacAddress(bytes))
+}
+
+#[derive(Debug)]
+pub enum SecurityLevel {
+    AuthPriv(String),
+}
+
+#[derive(Debug)]
+pub enum Error {
+    NetworkError(String),
+    AuthenticationError(String),
+    ConfigurationError(String),
+    TimeoutError(String),
+    UnexpectedError(String),
+    CommandError(String),
+}
+
+impl Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::NetworkError(msg) => write!(f, "Network error: {msg}"),
+            Error::AuthenticationError(msg) => write!(f, "Authentication error: {msg}"),
+            Error::ConfigurationError(msg) => write!(f, "Configuration error: {msg}"),
+            Error::TimeoutError(msg) => write!(f, "Timeout error: {msg}"),
+            Error::UnexpectedError(msg) => write!(f, "Unexpected error: {msg}"),
+            Error::CommandError(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl From<Error> for String {
+    fn from(val: Error) -> Self {
+        format!("{val}")
+    }
+}
+
+impl std::error::Error for Error {}
+
+impl From<russh::Error> for Error {
+    fn from(value: russh::Error) -> Self {
+        Error::NetworkError(format!("Russh client error: {value}"))
+    }
+}

brocade/src/network_operating_system.rs

@@ -0,0 +1,352 @@
+use std::str::FromStr;
+
+use async_trait::async_trait;
+use harmony_types::switch::{PortDeclaration, PortLocation};
+use log::{debug, info};
+use regex::Regex;
+
+use crate::{
+    BrocadeClient, BrocadeInfo, Error, ExecutionMode, InterSwitchLink, InterfaceInfo,
+    InterfaceStatus, InterfaceType, MacAddressEntry, PortChannelId, PortOperatingMode,
+    SecurityLevel, parse_brocade_mac_address, shell::BrocadeShell,
+};
+
+#[derive(Debug)]
+pub struct NetworkOperatingSystemClient {
+    shell: BrocadeShell,
+    version: BrocadeInfo,
+}
+
+impl NetworkOperatingSystemClient {
+    pub fn init(mut shell: BrocadeShell, version_info: BrocadeInfo) -> Self {
+        shell.before_all(vec!["terminal length 0".into()]);
+
+        Self {
+            shell,
+            version: version_info,
+        }
+    }
+
+    fn parse_mac_entry(&self, line: &str) -> Option<Result<MacAddressEntry, Error>> {
+        debug!("[Brocade] Parsing mac address entry: {line}");
+        let parts: Vec<&str> = line.split_whitespace().collect();
+        if parts.len() < 5 {
+            return None;
+        }
+
+        let (vlan, mac_address, port) = match parts.len() {
+            5 => (
+                u16::from_str(parts[0]).ok()?,
+                parse_brocade_mac_address(parts[1]).ok()?,
+                parts[4].to_string(),
+            ),
+            _ => (
+                u16::from_str(parts[0]).ok()?,
+                parse_brocade_mac_address(parts[1]).ok()?,
+                parts[5].to_string(),
+            ),
+        };
+
+        let port =
+            PortDeclaration::parse(&port).map_err(|e| Error::UnexpectedError(format!("{e}")));
+
+        match port {
+            Ok(p) => Some(Ok(MacAddressEntry {
+                vlan,
+                mac_address,
+                port: p,
+            })),
+            Err(e) => Some(Err(e)),
+        }
+    }
+
+    fn parse_inter_switch_link_entry(&self, line: &str) -> Option<Result<InterSwitchLink, Error>> {
+        debug!("[Brocade] Parsing inter switch link entry: {line}");
+        let parts: Vec<&str> = line.split_whitespace().collect();
+        if parts.len() < 10 {
+            return None;
+        }
+
+        let local_port = PortLocation::from_str(parts[2]).ok()?;
+        let remote_port = PortLocation::from_str(parts[5]).ok()?;
+
+        Some(Ok(InterSwitchLink {
+            local_port,
+            remote_port: Some(remote_port),
+        }))
+    }
+
+    fn parse_interface_status_entry(&self, line: &str) -> Option<Result<InterfaceInfo, Error>> {
+        debug!("[Brocade] Parsing interface status entry: {line}");
+        let parts: Vec<&str> = line.split_whitespace().collect();
+        if parts.len() < 6 {
+            return None;
+        }
+
+        let interface_type = match parts[0] {
+            "Fo" => InterfaceType::Ethernet("FortyGigabitEthernet".to_string()),
+            "Te" => InterfaceType::Ethernet("TenGigabitEthernet".to_string()),
+            _ => return None,
+        };
+        let port_location = PortLocation::from_str(parts[1]).ok()?;
+        let status = match parts[2] {
+            "connected" => InterfaceStatus::Connected,
+            "notconnected" => InterfaceStatus::NotConnected,
+            "sfpAbsent" => InterfaceStatus::SfpAbsent,
+            _ => return None,
+        };
+        let operating_mode = match parts[3] {
+            "ISL" => Some(PortOperatingMode::Fabric),
+            "Trunk" => Some(PortOperatingMode::Trunk),
+            "Access" => Some(PortOperatingMode::Access),
+            "--" => None,
+            _ => return None,
+        };
+
+        Some(Ok(InterfaceInfo {
+            name: format!("{interface_type} {port_location}"),
+            port_location,
+            interface_type,
+            operating_mode,
+            status,
+        }))
+    }
+
+    fn map_configure_interfaces_error(&self, err: Error) -> Error {
+        debug!("[Brocade] {err}");
+
+        if let Error::CommandError(message) = &err {
+            if message.contains("switchport")
+                && message.contains("Cannot configure aggregator member")
+            {
+                let re = Regex::new(r"\(conf-if-([a-zA-Z]+)-([\d/]+)\)#").unwrap();
+
+                if let Some(caps) = re.captures(message) {
+                    let interface_type = &caps[1];
+                    let port_location = &caps[2];
+                    let interface = format!("{interface_type} {port_location}");
+
+                    return Error::CommandError(format!(
+                        "Cannot configure interface '{interface}', it is a member of a port-channel (LAG)"
+                    ));
+                }
+            }
+        }
+
+        err
+    }
+}
+
+#[async_trait]
+impl BrocadeClient for NetworkOperatingSystemClient {
+    async fn version(&self) -> Result<BrocadeInfo, Error> {
+        Ok(self.version.clone())
+    }
+
+    async fn get_mac_address_table(&self) -> Result<Vec<MacAddressEntry>, Error> {
+        let output = self
+            .shell
+            .run_command("show mac-address-table", ExecutionMode::Regular)
+            .await?;
+
+        output
+            .lines()
+            .skip(1)
+            .filter_map(|line| self.parse_mac_entry(line))
+            .collect()
+    }
+
+    async fn get_stack_topology(&self) -> Result<Vec<InterSwitchLink>, Error> {
+        let output = self
+            .shell
+            .run_command("show fabric isl", ExecutionMode::Regular)
+            .await?;
+
+        output
+            .lines()
+            .skip(6)
+            .filter_map(|line| self.parse_inter_switch_link_entry(line))
+            .collect()
+    }
+
+    async fn get_interfaces(&self) -> Result<Vec<InterfaceInfo>, Error> {
+        let output = self
+            .shell
+            .run_command(
+                "show interface status rbridge-id all",
+                ExecutionMode::Regular,
+            )
+            .await?;
+
+        output
+            .lines()
+            .skip(2)
+            .filter_map(|line| self.parse_interface_status_entry(line))
+            .collect()
+    }
+
+    async fn configure_interfaces(
+        &self,
+        interfaces: &Vec<(String, PortOperatingMode)>,
+    ) -> Result<(), Error> {
+        info!("[Brocade] Configuring {} interface(s)...", interfaces.len());
+
+        let mut commands = vec!["configure terminal".to_string()];
+
+        for interface in interfaces {
+            commands.push(format!("interface {}", interface.0));
+
+            match interface.1 {
+                PortOperatingMode::Fabric => {
+                    commands.push("fabric isl enable".into());
+                    commands.push("fabric trunk enable".into());
+                }
+                PortOperatingMode::Trunk => {
+                    commands.push("switchport".into());
+                    commands.push("switchport mode trunk".into());
+                    commands.push("switchport trunk allowed vlan all".into());
+                    commands.push("no switchport trunk tag native-vlan".into());
+                    commands.push("spanning-tree shutdown".into());
+                    commands.push("no fabric isl enable".into());
+                    commands.push("no fabric trunk enable".into());
+                    commands.push("no shutdown".into());
+                }
+                PortOperatingMode::Access => {
+                    commands.push("switchport".into());
+                    commands.push("switchport mode access".into());
+                    commands.push("switchport access vlan 1".into());
+                    commands.push("no spanning-tree shutdown".into());
+                    commands.push("no fabric isl enable".into());
+                    commands.push("no fabric trunk enable".into());
+                }
+            }
+
+            commands.push("no shutdown".into());
+            commands.push("exit".into());
+        }
+
+        self.shell
+            .run_commands(commands, ExecutionMode::Regular)
+            .await
+            .map_err(|err| self.map_configure_interfaces_error(err))?;
+
+        info!("[Brocade] Interfaces configured.");
+
+        Ok(())
+    }
+
+    async fn find_available_channel_id(&self) -> Result<PortChannelId, Error> {
+        info!("[Brocade] Finding next available channel id...");
+
+        let output = self
+            .shell
+            .run_command("show port-channel summary", ExecutionMode::Regular)
+            .await?;
+
+        let used_ids: Vec<u8> = output
+            .lines()
+            .skip(6)
+            .filter_map(|line| {
+                let parts: Vec<&str> = line.split_whitespace().collect();
+                if parts.len() < 8 {
+                    return None;
+                }
+
+                u8::from_str(parts[0]).ok()
+            })
+            .collect();
+
+        let mut next_id: u8 = 1;
+        loop {
+            if !used_ids.contains(&next_id) {
+                break;
+            }
+            next_id += 1;
+        }
+
+        info!("[Brocade] Found channel id: {next_id}");
+        Ok(next_id)
+    }
+
+    async fn create_port_channel(
+        &self,
+        channel_id: PortChannelId,
+        channel_name: &str,
+        ports: &[PortLocation],
+    ) -> Result<(), Error> {
+        info!(
+            "[Brocade] Configuring port-channel '{channel_id} {channel_name}' with ports: {}",
+            ports
+                .iter()
+                .map(|p| format!("{p}"))
+                .collect::<Vec<String>>()
+                .join(", ")
+        );
+
+        let interfaces = self.get_interfaces().await?;
+
+        let mut commands = vec![
+            "configure terminal".into(),
+            format!("interface port-channel {}", channel_id),
+            "no shutdown".into(),
+            "exit".into(),
+        ];
+
+        for port in ports {
+            let interface = interfaces.iter().find(|i| i.port_location == *port);
+            let Some(interface) = interface else {
+                continue;
+            };
+
+            commands.push(format!("interface {}", interface.name));
+            commands.push("no switchport".into());
+            commands.push("no ip address".into());
+            commands.push("no fabric isl enable".into());
+            commands.push("no fabric trunk enable".into());
+            commands.push(format!("channel-group {channel_id} mode active"));
+            commands.push("no shutdown".into());
+            commands.push("exit".into());
+        }
+
+        self.shell
+            .run_commands(commands, ExecutionMode::Regular)
+            .await?;
+
+        info!("[Brocade] Port-channel '{channel_name}' configured.");
+
+        Ok(())
+    }
+
+    async fn clear_port_channel(&self, channel_name: &str) -> Result<(), Error> {
+        info!("[Brocade] Clearing port-channel: {channel_name}");
+
+        let commands = vec![
+            "configure terminal".into(),
+            format!("no interface port-channel {}", channel_name),
+            "exit".into(),
+        ];
+
+        self.shell
+            .run_commands(commands, ExecutionMode::Regular)
+            .await?;
+
+        info!("[Brocade] Port-channel '{channel_name}' cleared.");
+        Ok(())
+    }
+
+    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error> {
+        let commands = vec![
+            "configure terminal".into(),
+            "snmp-server view ALL 1 included".into(),
+            "snmp-server group public v3 priv read ALL".into(),
+            format!(
+                "snmp-server user {user_name} groupname public auth md5 auth-password {auth} priv des priv-password {des}"
+            ),
+            "exit".into(),
+        ];
+        self.shell
+            .run_commands(commands, ExecutionMode::Regular)
+            .await?;
+        Ok(())
+    }
+}

brocade/src/shell.rs

@@ -0,0 +1,367 @@
+use std::net::IpAddr;
+use std::time::Duration;
+use std::time::Instant;
+
+use crate::BrocadeOptions;
+use crate::Error;
+use crate::ExecutionMode;
+use crate::TimeoutConfig;
+use crate::ssh;
+
+use log::debug;
+use log::info;
+use russh::ChannelMsg;
+use tokio::time::timeout;
+
+#[derive(Debug)]
+pub struct BrocadeShell {
+    ip: IpAddr,
+    username: String,
+    password: String,
+    options: BrocadeOptions,
+    before_all_commands: Vec<String>,
+    after_all_commands: Vec<String>,
+}
+
+impl BrocadeShell {
+    pub async fn init(
+        ip_addresses: &[IpAddr],
+        username: &str,
+        password: &str,
+        options: &BrocadeOptions,
+    ) -> Result<Self, Error> {
+        let ip = ip_addresses
+            .first()
+            .ok_or_else(|| Error::ConfigurationError("No IP addresses provided".to_string()))?;
+
+        let brocade_ssh_client_options =
+            ssh::try_init_client(username, password, ip, options).await?;
+
+        Ok(Self {
+            ip: *ip,
+            username: username.to_string(),
+            password: password.to_string(),
+            before_all_commands: vec![],
+            after_all_commands: vec![],
+            options: brocade_ssh_client_options,
+        })
+    }
+
+    pub async fn open_session(&self, mode: ExecutionMode) -> Result<BrocadeSession, Error> {
+        BrocadeSession::open(
+            self.ip,
+            self.options.ssh.port,
+            &self.username,
+            &self.password,
+            self.options.clone(),
+            mode,
+        )
+        .await
+    }
+
+    pub async fn with_session<F, R>(&self, mode: ExecutionMode, callback: F) -> Result<R, Error>
+    where
+        F: FnOnce(
+            &mut BrocadeSession,
+        ) -> std::pin::Pin<
+            Box<dyn std::future::Future<Output = Result<R, Error>> + Send + '_>,
+        >,
+    {
+        let mut session = self.open_session(mode).await?;
+
+        let _ = session.run_commands(self.before_all_commands.clone()).await;
+        let result = callback(&mut session).await;
+        let _ = session.run_commands(self.after_all_commands.clone()).await;
+
+        session.close().await?;
+        result
+    }
+
+    pub async fn run_command(&self, command: &str, mode: ExecutionMode) -> Result<String, Error> {
+        let mut session = self.open_session(mode).await?;
+
+        let _ = session.run_commands(self.before_all_commands.clone()).await;
+        let result = session.run_command(command).await;
+        let _ = session.run_commands(self.after_all_commands.clone()).await;
+
+        session.close().await?;
+        result
+    }
+
+    pub async fn run_commands(
+        &self,
+        commands: Vec<String>,
+        mode: ExecutionMode,
+    ) -> Result<(), Error> {
+        let mut session = self.open_session(mode).await?;
+
+        let _ = session.run_commands(self.before_all_commands.clone()).await;
+        let result = session.run_commands(commands).await;
+        let _ = session.run_commands(self.after_all_commands.clone()).await;
+
+        session.close().await?;
+        result
+    }
+
+    pub fn before_all(&mut self, commands: Vec<String>) {
+        self.before_all_commands = commands;
+    }
+
+    pub fn after_all(&mut self, commands: Vec<String>) {
+        self.after_all_commands = commands;
+    }
+}
+
+pub struct BrocadeSession {
+    pub channel: russh::Channel<russh::client::Msg>,
+    pub mode: ExecutionMode,
+    pub options: BrocadeOptions,
+}
+
+impl BrocadeSession {
+    pub async fn open(
+        ip: IpAddr,
+        port: u16,
+        username: &str,
+        password: &str,
+        options: BrocadeOptions,
+        mode: ExecutionMode,
+    ) -> Result<Self, Error> {
+        let client = ssh::create_client(ip, port, username, password, &options).await?;
+        let mut channel = client.channel_open_session().await?;
+
+        channel
+            .request_pty(false, "vt100", 80, 24, 0, 0, &[])
+            .await?;
+        channel.request_shell(false).await?;
+
+        wait_for_shell_ready(&mut channel, &options.timeouts).await?;
+
+        if let ExecutionMode::Privileged = mode {
+            try_elevate_session(&mut channel, username, password, &options.timeouts).await?;
+        }
+
+        Ok(Self {
+            channel,
+            mode,
+            options,
+        })
+    }
+
+    pub async fn close(&mut self) -> Result<(), Error> {
+        debug!("[Brocade] Closing session...");
+
+        self.channel.data(&b"exit\n"[..]).await?;
+        if let ExecutionMode::Privileged = self.mode {
+            self.channel.data(&b"exit\n"[..]).await?;
+        }
+
+        let start = Instant::now();
+        while start.elapsed() < self.options.timeouts.cleanup {
+            match timeout(self.options.timeouts.message_wait, self.channel.wait()).await {
+                Ok(Some(ChannelMsg::Close)) => break,
+                Ok(Some(_)) => continue,
+                Ok(None) | Err(_) => break,
+            }
+        }
+
+        debug!("[Brocade] Session closed.");
+        Ok(())
+    }
+
+    pub async fn run_command(&mut self, command: &str) -> Result<String, Error> {
+        if self.should_skip_command(command) {
+            return Ok(String::new());
+        }
+
+        debug!("[Brocade] Running command: '{command}'...");
+
+        self.channel
+            .data(format!("{}\n", command).as_bytes())
+            .await?;
+        tokio::time::sleep(Duration::from_millis(100)).await;
+
+        let output = self.collect_command_output().await?;
+        let output = String::from_utf8(output)
+            .map_err(|_| Error::UnexpectedError("Invalid UTF-8 in command output".to_string()))?;
+
+        self.check_for_command_errors(&output, command)?;
+        Ok(output)
+    }
+
+    pub async fn run_commands(&mut self, commands: Vec<String>) -> Result<(), Error> {
+        for command in commands {
+            self.run_command(&command).await?;
+        }
+        Ok(())
+    }
+
+    fn should_skip_command(&self, command: &str) -> bool {
+        if (command.starts_with("write") || command.starts_with("deploy")) && self.options.dry_run {
+            info!("[Brocade] Dry-run mode enabled, skipping command: {command}");
+            return true;
+        }
+        false
+    }
+
+    async fn collect_command_output(&mut self) -> Result<Vec<u8>, Error> {
+        let mut output = Vec::new();
+        let start = Instant::now();
+        let read_timeout = Duration::from_millis(500);
+        let log_interval = Duration::from_secs(5);
+        let mut last_log = Instant::now();
+
+        loop {
+            if start.elapsed() > self.options.timeouts.command_execution {
+                return Err(Error::TimeoutError(
+                    "Timeout waiting for command completion.".into(),
+                ));
+            }
+
+            if start.elapsed() > self.options.timeouts.command_output
+                && last_log.elapsed() > log_interval
+            {
+                info!("[Brocade] Waiting for command output...");
+                last_log = Instant::now();
+            }
+
+            match timeout(read_timeout, self.channel.wait()).await {
+                Ok(Some(ChannelMsg::Data { data } | ChannelMsg::ExtendedData { data, .. })) => {
+                    output.extend_from_slice(&data);
+                    let current_output = String::from_utf8_lossy(&output);
+                    if current_output.contains('>') || current_output.contains('#') {
+                        return Ok(output);
+                    }
+                }
+                Ok(Some(ChannelMsg::Eof | ChannelMsg::Close)) => return Ok(output),
+                Ok(Some(ChannelMsg::ExitStatus { exit_status })) => {
+                    debug!("[Brocade] Command exit status: {exit_status}");
+                }
+                Ok(Some(_)) => continue,
+                Ok(None) | Err(_) => {
+                    if output.is_empty() {
+                        if let Ok(None) = timeout(read_timeout, self.channel.wait()).await {
+                            break;
+                        }
+                        continue;
+                    }
+
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                    let current_output = String::from_utf8_lossy(&output);
+                    if current_output.contains('>') || current_output.contains('#') {
+                        return Ok(output);
+                    }
+                }
+            }
+        }
+
+        Ok(output)
+    }
+
+    fn check_for_command_errors(&self, output: &str, command: &str) -> Result<(), Error> {
+        const ERROR_PATTERNS: &[&str] = &[
+            "invalid input",
+            "syntax error",
+            "command not found",
+            "unknown command",
+            "permission denied",
+            "access denied",
+            "authentication failed",
+            "configuration error",
+            "failed to",
+            "error:",
+        ];
+
+        let output_lower = output.to_lowercase();
+        if ERROR_PATTERNS.iter().any(|&p| output_lower.contains(p)) {
+            return Err(Error::CommandError(format!(
+                "Command error: {}",
+                output.trim()
+            )));
+        }
+
+        if !command.starts_with("show") && output.trim().is_empty() {
+            return Err(Error::CommandError(format!(
+                "Command '{command}' produced no output"
+            )));
+        }
+
+        Ok(())
+    }
+}
+
+async fn wait_for_shell_ready(
+    channel: &mut russh::Channel<russh::client::Msg>,
+    timeouts: &TimeoutConfig,
+) -> Result<(), Error> {
+    let mut buffer = Vec::new();
+    let start = Instant::now();
+
+    while start.elapsed() < timeouts.shell_ready {
+        match timeout(timeouts.message_wait, channel.wait()).await {
+            Ok(Some(ChannelMsg::Data { data })) => {
+                buffer.extend_from_slice(&data);
+                let output = String::from_utf8_lossy(&buffer);
+                let output = output.trim();
+                if output.ends_with('>') || output.ends_with('#') {
+                    debug!("[Brocade] Shell ready");
+                    return Ok(());
+                }
+            }
+            Ok(Some(_)) => continue,
+            Ok(None) => break,
+            Err(_) => continue,
+        }
+    }
+    Ok(())
+}
+
+async fn try_elevate_session(
+    channel: &mut russh::Channel<russh::client::Msg>,
+    username: &str,
+    password: &str,
+    timeouts: &TimeoutConfig,
+) -> Result<(), Error> {
+    channel.data(&b"enable\n"[..]).await?;
+    let start = Instant::now();
+    let mut buffer = Vec::new();
+
+    while start.elapsed() < timeouts.shell_ready {
+        match timeout(timeouts.message_wait, channel.wait()).await {
+            Ok(Some(ChannelMsg::Data { data })) => {
+                buffer.extend_from_slice(&data);
+                let output = String::from_utf8_lossy(&buffer);
+
+                if output.ends_with('#') {
+                    debug!("[Brocade] Privileged mode established");
+                    return Ok(());
+                }
+
+                if output.contains("User Name:") {
+                    channel.data(format!("{}\n", username).as_bytes()).await?;
+                    buffer.clear();
+                } else if output.contains("Password:") {
+                    channel.data(format!("{}\n", password).as_bytes()).await?;
+                    buffer.clear();
+                } else if output.contains('>') {
+                    return Err(Error::AuthenticationError(
+                        "Enable authentication failed".into(),
+                    ));
+                }
+            }
+            Ok(Some(_)) => continue,
+            Ok(None) => break,
+            Err(_) => continue,
+        }
+    }
+
+    let output = String::from_utf8_lossy(&buffer);
+    if output.ends_with('#') {
+        debug!("[Brocade] Privileged mode established");
+        Ok(())
+    } else {
+        Err(Error::AuthenticationError(format!(
+            "Enable failed. Output:\n{output}"
+        )))
+    }
+}

brocade/src/ssh.rs

@@ -0,0 +1,131 @@
+use std::borrow::Cow;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use log::debug;
+use russh::client::Handler;
+use russh::kex::DH_G1_SHA1;
+use russh::kex::ECDH_SHA2_NISTP256;
+use russh_keys::key::SSH_RSA;
+
+use super::BrocadeOptions;
+use super::Error;
+
+#[derive(Clone, Debug)]
+pub struct SshOptions {
+    pub preferred_algorithms: russh::Preferred,
+    pub port: u16,
+}
+
+impl Default for SshOptions {
+    fn default() -> Self {
+        Self {
+            preferred_algorithms: Default::default(),
+            port: 22,
+        }
+    }
+}
+
+impl SshOptions {
+    fn ecdhsa_sha2_nistp256(port: u16) -> Self {
+        Self {
+            preferred_algorithms: russh::Preferred {
+                kex: Cow::Borrowed(&[ECDH_SHA2_NISTP256]),
+                key: Cow::Borrowed(&[SSH_RSA]),
+                ..Default::default()
+            },
+            port,
+            ..Default::default()
+        }
+    }
+
+    fn legacy(port: u16) -> Self {
+        Self {
+            preferred_algorithms: russh::Preferred {
+                kex: Cow::Borrowed(&[DH_G1_SHA1]),
+                key: Cow::Borrowed(&[SSH_RSA]),
+                ..Default::default()
+            },
+            port,
+            ..Default::default()
+        }
+    }
+}
+
+pub struct Client;
+
+#[async_trait]
+impl Handler for Client {
+    type Error = Error;
+
+    async fn check_server_key(
+        &mut self,
+        _server_public_key: &russh_keys::key::PublicKey,
+    ) -> Result<bool, Self::Error> {
+        Ok(true)
+    }
+}
+
+pub async fn try_init_client(
+    username: &str,
+    password: &str,
+    ip: &std::net::IpAddr,
+    base_options: &BrocadeOptions,
+) -> Result<BrocadeOptions, Error> {
+    let mut default = SshOptions::default();
+    default.port = base_options.ssh.port;
+    let ssh_options = vec![
+        default,
+        SshOptions::ecdhsa_sha2_nistp256(base_options.ssh.port),
+        SshOptions::legacy(base_options.ssh.port),
+    ];
+
+    for ssh in ssh_options {
+        let opts = BrocadeOptions {
+            ssh: ssh.clone(),
+            ..base_options.clone()
+        };
+        debug!("Creating client {ip}:{} {username}", ssh.port);
+        let client = create_client(*ip, ssh.port, username, password, &opts).await;
+
+        match client {
+            Ok(_) => {
+                return Ok(opts);
+            }
+            Err(e) => match e {
+                Error::NetworkError(e) => {
+                    if e.contains("No common key exchange algorithm") {
+                        continue;
+                    } else {
+                        return Err(Error::NetworkError(e));
+                    }
+                }
+                _ => return Err(e),
+            },
+        }
+    }
+
+    Err(Error::NetworkError(
+        "Could not establish ssh connection: wrong key exchange algorithm)".to_string(),
+    ))
+}
+
+pub async fn create_client(
+    ip: std::net::IpAddr,
+    port: u16,
+    username: &str,
+    password: &str,
+    options: &BrocadeOptions,
+) -> Result<russh::client::Handle<Client>, Error> {
+    let config = russh::client::Config {
+        preferred: options.ssh.preferred_algorithms.clone(),
+        ..Default::default()
+    };
+    let mut client = russh::client::connect(Arc::new(config), (ip, port), Client {}).await?;
+    if !client.authenticate_password(username, password).await? {
+        return Err(Error::AuthenticationError(
+            "ssh authentication failed".to_string(),
+        ));
+    }
+    Ok(client)
+}

check.sh

@@ -1,5 +1,8 @@
 #!/bin/sh
 set -e
+
+rustc --version
 cargo check --all-targets --all-features --keep-going
 cargo fmt --check
+cargo clippy
 cargo test

data/okd/installer_image/scos-live-initramfs.x86_64.img

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-initramfs.x86_64.img

data/okd/installer_image/scos-live-kernel.x86_64

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-kernel.x86_64

data/okd/installer_image/scos-live-rootfs.x86_64.img

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-rootfs.x86_64.img

data/pxe/okd/README.md

@@ -0,0 +1,8 @@
+Here lies all the data files required for an OKD cluster PXE boot setup.
+
+This inclues ISO files, binary boot files, ipxe, etc.
+
+TODO as of august 2025 :
+
+- `harmony_inventory_agent` should be downloaded from official releases, this embedded version is practical for now though
+- The cluster ssh key should be generated and handled by harmony with the private key saved in a secret store

data/pxe/okd/http_files/.gitattributes

@@ -0,0 +1,9 @@
+harmony_inventory_agent filter=lfs diff=lfs merge=lfs -text
+os filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9 filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/initrd.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/vmlinuz filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/efiboot.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/install.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/pxeboot filter=lfs diff=lfs merge=lfs -text

data/pxe/okd/http_files/cluster_ssh_key.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx6bDylvC68cVpjKfEFtLQJ/dOFi6PVS2vsIOqPDJIc jeangab@liliane2

demos/cncf-k8s-quebec-meetup-september-2025/.gitignore

@@ -0,0 +1,3 @@
+.terraform
+*.tfstate
+venv

demos/cncf-k8s-quebec-meetup-september-2025/README.md

@@ -0,0 +1,5 @@
+To build :
+
+```bash
+npx @marp-team/marp-cli@latest -w slides.md
+```

demos/cncf-k8s-quebec-meetup-september-2025/ansible/README.md

@@ -0,0 +1,9 @@
+To run this :
+
+```bash
+virtualenv venv
+source venv/bin/activate
+pip install ansible ansible-dev-tools
+ansible-lint download.yml
+ansible-playbook -i localhost download.yml
+```

demos/cncf-k8s-quebec-meetup-september-2025/ansible/download.yml

@@ -0,0 +1,8 @@
+- name: Test Ansible URL Validation
+  hosts: localhost
+  tasks:
+    - name: Download a file
+      ansible.builtin.get_url:
+        url: "http:/wikipedia.org/"
+        dest: "/tmp/ansible-test/wikipedia.html"
+        mode: '0900'

demos/cncf-k8s-quebec-meetup-september-2025/slides.md

@@ -0,0 +1,241 @@
+---
+theme: uncover
+---
+
+# Voici l'histoire de Petit Poisson
+
+---
+
+<img src="./Happy_swimmer.jpg" width="600"/>
+
+---
+
+<img src="./happy_landscape_swimmer.jpg" width="1000"/>
+
+---
+
+<img src="./Happy_swimmer.jpg" width="200"/>
+
+<img src="./tryrust.org.png" width="600"/>
+
+[https://tryrust.org](https://tryrust.org)
+
+---
+
+<img src="./texto_deploy_prod_1.png" width="600"/>
+
+---
+
+<img src="./texto_deploy_prod_2.png" width="600"/>
+
+---
+
+<img src="./texto_deploy_prod_3.png" width="600"/>
+
+---
+
+<img src="./texto_deploy_prod_4.png" width="600"/>
+
+---
+
+## Demo time
+
+---
+
+<img src="./Happy_swimmer_sunglasses.jpg" width="1000"/>
+
+---
+
+<img src="./texto_download_wikipedia.png" width="600"/>
+
+---
+
+<img src="./ansible.jpg" width="200"/>
+
+## Ansible❓
+
+---
+
+<img src="./Happy_swimmer.jpg" width="200"/>
+
+```yaml
+- name: Download wikipedia
+  hosts: localhost
+  tasks:
+    - name: Download a file
+      ansible.builtin.get_url:
+        url: "https:/wikipedia.org/"
+        dest: "/tmp/ansible-test/wikipedia.html"
+        mode: '0900'
+```
+
+---
+
+<img src="./Happy_swimmer.jpg" width="200"/>
+
+```
+ansible-lint download.yml
+
+Passed: 0 failure(s), 0 warning(s) on 1 files. Last profile that met the validation criteria was 'production'.
+```
+
+---
+
+```
+git push
+```
+
+---
+
+<img src="./75_years_later.jpg" width="1100"/>
+
+---
+
+<img src="./texto_download_wikipedia_fail.png" width="600"/>
+
+---
+
+<img src="./Happy_swimmer_reversed.jpg" width="600"/>
+
+---
+
+<img src="./ansible_output_fail.jpg" width="1100"/>
+
+---
+
+<img src="./Happy_swimmer_reversed_1hit.jpg" width="600"/>
+
+---
+
+<img src="./ansible_crossed_out.jpg" width="400"/>
+
+---
+
+
+<img src="./terraform.jpg" width="400"/>
+
+## Terraform❓❗
+
+---
+
+<img src="./Happy_swimmer_reversed_1hit.jpg" width="200"/>
+<img src="./terraform.jpg" width="200"/>
+
+```tf
+provider "docker" {}
+
+resource "docker_network" "invalid_network" {
+  name = "my-invalid-network"
+
+  ipam_config {
+    subnet = "172.17.0.0/33"
+  }
+}
+```
+
+---
+
+<img src="./Happy_swimmer_reversed_1hit.jpg" width="100"/>
+<img src="./terraform.jpg" width="200"/>
+
+```
+terraform plan
+
+Terraform used the selected providers to generate the following execution plan.
+Resource actions are indicated with the following symbols:
+  + create
+
+Terraform will perform the following actions:
+
+  # docker_network.invalid_network will be created
+  + resource "docker_network" "invalid_network" {
+      + driver      = (known after apply)
+      + id          = (known after apply)
+      + internal    = (known after apply)
+      + ipam_driver = "default"
+      + name        = "my-invalid-network"
+      + options     = (known after apply)
+      + scope       = (known after apply)
+
+      + ipam_config {
+          + subnet   = "172.17.0.0/33"
+            # (2 unchanged attributes hidden)
+        }
+    }
+
+Plan: 1 to add, 0 to change, 0 to destroy.
+```
+
+---
+
+✅
+
+---
+
+```
+terraform apply
+```
+
+---
+
+```
+Plan: 1 to add, 0 to change, 0 to destroy.
+
+Do you want to perform these actions?
+  Terraform will perform the actions described above.
+  Only 'yes' will be accepted to approve.
+
+  Enter a value: yes
+```
+
+---
+
+```
+docker_network.invalid_network: Creating...
+╷
+│ Error: Unable to create network: Error response from daemon: invalid network config:
+│ invalid subnet 172.17.0.0/33: invalid CIDR block notation
+│
+│   with docker_network.invalid_network,
+│   on main.tf line 11, in resource "docker_network" "invalid_network":
+│   11: resource "docker_network" "invalid_network" {
+│
+╵
+```
+
+---
+
+
+<img src="./Happy_swimmer_reversed_fullhit.jpg" width="1100"/>
+
+---
+
+<img src="./ansible_crossed_out.jpg" width="300"/>
+<img src="./terraform_crossed_out.jpg" width="400"/>
+<img src="./Happy_swimmer_reversed_fullhit.jpg" width="300"/>
+
+---
+
+## Harmony❓❗
+
+---
+
+Demo time
+
+---
+
+<img src="./Happy_swimmer.jpg" width="300"/>
+
+---
+
+# 🎼 
+
+Harmony : [https://git.nationtech.io/nationtech/harmony](https://git.nationtech.io/nationtech/harmony)
+
+
+ <img src="./qrcode_gitea_nationtech.png" width="120"/>
+
+
+LinkedIn : [https://www.linkedin.com/in/jean-gabriel-gill-couture/](https://www.linkedin.com/in/jean-gabriel-gill-couture/)
+
+Courriel : [jg@nationtech.io](mailto:jg@nationtech.io)

demos/cncf-k8s-quebec-meetup-september-2025/storyline.md

@@ -0,0 +1,132 @@
+# Harmony, Orchestrateur d'infrastructure open-source
+
+**Target Duration:** 25 minutes\
+**Tone:** Friendly, expert-to-expert, inspiring.
+
+---
+
+#### **Slide 1: Title Slide**
+
+- **Visual:** Clean and simple. Your company logo (NationTech) and the Harmony logo.
+
+---
+
+#### **Slide 2: The YAML Labyrinth**
+
+**Goal:** Get every head in the room nodding in agreement. Start with their world, not yours.
+
+- **Visual:**
+  - Option A: "The Pull Request from Hell". A screenshot of a GitHub pull request for a seemingly minor change that touches dozens of YAML files across multiple directories. A sea of red and green diffs that is visually overwhelming.
+  - Option B: A complex flowchart connecting dozens of logos: Terraform, Ansible, K8s, Helm, etc.
+- **Narration:**\
+  [...ADD SOMETHING FOR INTRODUCTION...]\
+  "We love the power that tools like Kubernetes and the CNCF landscape have given us. But let's be honest... when did our infrastructure code start looking like _this_?"\
+  "We have GitOps, which is great. But it often means we're managing this fragile cathedral of YAML, Helm charts, and brittle scripts. We spend more time debugging indentation and tracing variables than we do building truly resilient systems."
+
+---
+
+#### **Slide 3: The Real Cost of Infrastructure**
+
+- **Visual:** "The Jenga Tower of Tools". A tall, precarious Jenga tower where each block is the logo of a different tool (Terraform, K8s, Helm, Ansible, Prometheus, ArgoCD, etc.). One block near the bottom is being nervously pulled out.
+- **Narration:**
+  "The real cost isn't just complexity; it's the constant need to choose, learn, integrate, and operate a dozen different tools, each with its own syntax and failure modes. It's the nagging fear that a tiny typo in a config file could bring everything down. Click-ops isn't the answer, but the current state of IaC feels like we've traded one problem for another."
+
+---
+
+#### **Slide 4: The Broken Promise of "Code"**
+
+**Goal:** Introduce the core idea before introducing the product. This makes the solution feel inevitable.
+
+- **(Initial Visual):** A two-panel slide.
+  - **Left Panel Title: "The Plan"** - A terminal showing a green, successful `terraform plan` output.
+  - **Right Panel Title: "The Reality"** - The _next_ screen in the terminal, showing the `terraform apply` failing with a cascade of red error text.
+- **Narration:**
+  "We call our discipline **Infrastructure as Code**. And we've all been here. Our 'compiler' is a `terraform plan` that says everything looks perfect. We get the green light."
+  (Pause for a beat)
+  "And then we `apply`, and reality hits. It fails halfway through, at runtime, when it's most expensive and painful to fix."
+
+**(Click to transition the slide)**
+
+- **(New Visual):** The entire slide is replaced by a clean screenshot of a code editor (like nvim 😉) showing Harmony's Rust DSL. A red squiggly line is under a config line. The error message is clear in the "Problems" panel: `error: Incompatible deployment. Production target 'gcp-prod-cluster' requires a StorageClass with 'snapshots' capability, but 'standard-sc' does not provide it.`
+- **Narration (continued):**
+  "In software development, we solved these problems years ago. We don't accept 'it compiled, but crashed on startup'. We have real tools, type systems, compilers, test frameworks, and IDEs that catch our mistakes before they ever reach production. **So, what if we could treat our entire infrastructure... like a modern, compiled application?**"
+  "What if your infrastructure code could get compile-time checks, straight into the editor... instead of runtime panics and failures at 3 AM in production?"
+
+---
+
+#### **Slide 5: Introducing Harmony**
+
+**Goal:** Introduce Harmony as the answer to the "What If?" question.
+
+- **Visual:** The Harmony logo, large and centered.
+- **Tagline:** `Infrastructure in type-safe Rust. No YAML required.`
+- **Narration:**
+  "This is Harmony. It's an open-source orchestrator that lets you define your entire stack — from a dev laptop to a multi-site bare-metal cluster—in a single, type-safe Rust codebase."
+
+---
+
+#### **Slide 6: Before & After**
+
+- **Visual:** A side-by-side comparison. Left side: A screen full of complex, nested YAML. Right side: 10-15 lines of clean, readable Harmony Rust DSL that accomplishes the same thing.
+- **Narration:**
+  "This is the difference. On the left, the fragile world of strings and templates. On the right, a portable, verifiable program that describes your apps, your infra, and your operations. We unify scaffolding, provisioning, and Day-2 ops, all verified by the Rust compiler. But enough slides... let's see it in action."
+
+---
+
+#### **Slide 7: Live Demo: Zero to Monitored App**
+
+**Goal:** Show, don't just tell. Make it look effortless. This is where you build the "dream."
+
+- **Visual:** Your terminal/IDE, ready to go.
+- **Narration Guide:**
+  "Okay, for this demo, we're going to take a standard web app from GitHub. Nothing special about it."
+  _(Show the repo)_
+  "Now, let's bring it into Harmony. This is the entire definition we need to describe the application and its needs."
+  _(Show the Rust DSL)_
+  "First, let's run it locally on k3d. The exact same definition for dev as for prod."
+  _(Deploy locally, show it works)_
+  "Cool. But a real app needs monitoring. In Harmony, that's just adding a feature to our code."
+  _(Uncomment one line: `.with_feature(Monitoring)` and redeploy)_
+  "And just like that, we have a fully configured Prometheus and Grafana stack, scraping our app. No YAML, no extra config."
+  "Finally, let's push this to our production staging cluster. We just change the target and specify our multi-site Ceph storage."
+  _(Deploy to the remote cluster)_
+  "And there it is. We've gone from a simple web app to a monitored, enterprise-grade service in minutes."
+
+---
+
+#### **Slide 8: Live Demo: Embracing Chaos**
+
+**Goal:** Prove the "predictable" and "resilient" claims in the most dramatic way possible.
+
+- **Visual:** A slide showing a map or diagram of your distributed infrastructure (the different data centers). Then switch back to your terminal.
+- **Narration Guide:**
+  "This is great when things are sunny. But production is chaos. So... let's break things. On purpose."
+  "First, a network failure." _(Kill a switch/link, show app is still up)_
+  "Now, let's power off a storage server." _(Force off a server, show Ceph healing and the app is unaffected)_
+  "How about a control plane node?" _(Force off a k8s control plane, show the cluster is still running)_
+  "Okay, for the grand finale. What if we have a cascading failure? I'm going to kill _another_ storage server. This should cause a total failure in this data center."
+  _(Force off the second server, narrate what's happening)_
+  "And there it is... Ceph has lost quorum in this site... and Harmony has automatically failed everything over to our other datacenter. The app is still running."
+
+---
+
+#### **Slide 9: The New Reality**
+
+**Goal:** Summarize the dream and tell the audience what you want them to do.
+
+- **Visual:** The clean, simple Harmony Rust DSL code from Slide 6. A summary of what was just accomplished is listed next to it: `✓ GitHub to Prod in minutes`, `✓ Type-Safe Validation`, `✓ Built-in Monitoring`, `✓ Automated Multi-Site Failover`.
+- **Narration:**
+  "So, in just a few minutes, we went from a simple web app to a multi-site, monitored, and chaos-proof production deployment. We did it with a small amount of code that is easy to read, easy to verify, and completely portable. This is our vision: to offload the complexity, and make infrastructure simple, predictable, and even fun again."
+
+---
+
+#### **Slide 10: Join Us**
+
+- **Visual:** A clean, final slide with QR codes and links.
+  - GitHub Repo (`github.com/nation-tech/harmony`)
+  - Website (`harmony.sh` or similar)
+  - Your contact info (`jg@nation.tech` / LinkedIn / Twitter)
+- **Narration:**
+  "Harmony is open-source, AGPLv3. We believe this is the future, but we're just getting started. We know this crowd has great infrastructure minds out there, and we need your feedback. Please, check out the project on GitHub. Star it if you like what you see. Tell us what's missing. Let's build this future together. Thank you."
+
+**(Open for Q&A)**

demos/cncf-k8s-quebec-meetup-september-2025/terraform/.terraform.lock.hcl

@@ -0,0 +1,40 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
+
+provider "registry.terraform.io/hashicorp/http" {
+  version = "3.5.0"
+  hashes = [
+    "h1:8bUoPwS4hahOvzCBj6b04ObLVFXCEmEN8T/5eOHmWOM=",
+    "zh:047c5b4920751b13425efe0d011b3a23a3be97d02d9c0e3c60985521c9c456b7",
+    "zh:157866f700470207561f6d032d344916b82268ecd0cf8174fb11c0674c8d0736",
+    "zh:1973eb9383b0d83dd4fd5e662f0f16de837d072b64a6b7cd703410d730499476",
+    "zh:212f833a4e6d020840672f6f88273d62a564f44acb0c857b5961cdb3bbc14c90",
+    "zh:2c8034bc039fffaa1d4965ca02a8c6d57301e5fa9fff4773e684b46e3f78e76a",
+    "zh:5df353fc5b2dd31577def9cc1a4ebf0c9a9c2699d223c6b02087a3089c74a1c6",
+    "zh:672083810d4185076c81b16ad13d1224b9e6ea7f4850951d2ab8d30fa6e41f08",
+    "zh:78d5eefdd9e494defcb3c68d282b8f96630502cac21d1ea161f53cfe9bb483b3",
+    "zh:7b4200f18abdbe39904b03537e1a78f21ebafe60f1c861a44387d314fda69da6",
+    "zh:843feacacd86baed820f81a6c9f7bd32cf302db3d7a0f39e87976ebc7a7cc2ee",
+    "zh:a9ea5096ab91aab260b22e4251c05f08dad2ed77e43e5e4fadcdfd87f2c78926",
+    "zh:d02b288922811739059e90184c7f76d45d07d3a77cc48d0b15fd3db14e928623",
+  ]
+}
+
+provider "registry.terraform.io/hashicorp/local" {
+  version = "2.5.3"
+  hashes = [
+    "h1:1Nkh16jQJMp0EuDmvP/96f5Unnir0z12WyDuoR6HjMo=",
+    "zh:284d4b5b572eacd456e605e94372f740f6de27b71b4e1fd49b63745d8ecd4927",
+    "zh:40d9dfc9c549e406b5aab73c023aa485633c1b6b730c933d7bcc2fa67fd1ae6e",
+    "zh:6243509bb208656eb9dc17d3c525c89acdd27f08def427a0dce22d5db90a4c8b",
+    "zh:78d5eefdd9e494defcb3c68d282b8f96630502cac21d1ea161f53cfe9bb483b3",
+    "zh:885d85869f927853b6fe330e235cd03c337ac3b933b0d9ae827ec32fa1fdcdbf",
+    "zh:bab66af51039bdfcccf85b25fe562cbba2f54f6b3812202f4873ade834ec201d",
+    "zh:c505ff1bf9442a889ac7dca3ac05a8ee6f852e0118dd9a61796a2f6ff4837f09",
+    "zh:d36c0b5770841ddb6eaf0499ba3de48e5d4fc99f4829b6ab66b0fab59b1aaf4f",
+    "zh:ddb6a407c7f3ec63efb4dad5f948b54f7f4434ee1a2607a49680d494b1776fe1",
+    "zh:e0dafdd4500bec23d3ff221e3a9b60621c5273e5df867bc59ef6b7e41f5c91f6",
+    "zh:ece8742fd2882a8fc9d6efd20e2590010d43db386b920b2a9c220cfecc18de47",
+    "zh:f4c6b3eb8f39105004cf720e202f04f57e3578441cfb76ca27611139bc116a82",
+  ]
+}

demos/cncf-k8s-quebec-meetup-september-2025/terraform/main.tf

@@ -0,0 +1,10 @@
+provider "http" {}
+
+data "http" "remote_file" {
+  url = "http:/example.com/file.txt"
+}
+
+resource "local_file" "downloaded_file" {
+  content  = data.http.remote_file.body
+  filename = "${path.module}/downloaded_file.txt"
+}

demos/cncf-k8s-quebec-meetup-september-2025/terraform_2/.terraform.lock.hcl

@@ -0,0 +1,24 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
+
+provider "registry.terraform.io/kreuzwerker/docker" {
+  version     = "3.0.2"
+  constraints = "~> 3.0.1"
+  hashes = [
+    "h1:cT2ccWOtlfKYBUE60/v2/4Q6Stk1KYTNnhxSck+VPlU=",
+    "zh:15b0a2b2b563d8d40f62f83057d91acb02cd0096f207488d8b4298a59203d64f",
+    "zh:23d919de139f7cd5ebfd2ff1b94e6d9913f0977fcfc2ca02e1573be53e269f95",
+    "zh:38081b3fe317c7e9555b2aaad325ad3fa516a886d2dfa8605ae6a809c1072138",
+    "zh:4a9c5065b178082f79ad8160243369c185214d874ff5048556d48d3edd03c4da",
+    "zh:5438ef6afe057945f28bce43d76c4401254073de01a774760169ac1058830ac2",
+    "zh:60b7fadc287166e5c9873dfe53a7976d98244979e0ab66428ea0dea1ebf33e06",
+    "zh:61c5ec1cb94e4c4a4fb1e4a24576d5f39a955f09afb17dab982de62b70a9bdd1",
+    "zh:a38fe9016ace5f911ab00c88e64b156ebbbbfb72a51a44da3c13d442cd214710",
+    "zh:c2c4d2b1fd9ebb291c57f524b3bf9d0994ff3e815c0cd9c9bcb87166dc687005",
+    "zh:d567bb8ce483ab2cf0602e07eae57027a1a53994aba470fa76095912a505533d",
+    "zh:e83bf05ab6a19dd8c43547ce9a8a511f8c331a124d11ac64687c764ab9d5a792",
+    "zh:e90c934b5cd65516fbcc454c89a150bfa726e7cf1fe749790c7480bbeb19d387",
+    "zh:f05f167d2eaf913045d8e7b88c13757e3cf595dd5cd333057fdafc7c4b7fed62",
+    "zh:fcc9c1cea5ce85e8bcb593862e699a881bd36dffd29e2e367f82d15368659c3d",
+  ]
+}

demos/cncf-k8s-quebec-meetup-september-2025/terraform_2/main.tf

@@ -0,0 +1,17 @@
+terraform {
+  required_providers {
+    docker = {
+      source  = "kreuzwerker/docker"
+      version = "~> 3.0.1" # Adjust version as needed
+    }
+  }
+}
+provider "docker" {}
+
+resource "docker_network" "invalid_network" {
+  name = "my-invalid-network"
+
+  ipam_config {
+    subnet = "172.17.0.0/33"
+  }
+}

docs/OKD_Host_preparation.md

@@ -0,0 +1,8 @@
+## Bios settings
+
+1. CSM : Disabled (compatibility support to boot gpt formatted drives)
+2. Secure boot : disabled
+3. Boot order :
+    1. Local Hard drive
+    2. PXE IPv4
+4. System clock, make sure it is adjusted, otherwise you will get invalid certificates error

docs/README.md

@@ -1 +1,33 @@
-Not much here yet, see the `adr` folder for now. More to come in time!
+# 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**](./guides/getting-started.md): A step-by-step tutorial that takes you from an empty project to deploying your first application.
+- [**Core Concepts**](./concepts.md): 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.
+
+- [**OKD on Bare Metal**](./use-cases/okd-on-bare-metal.md): A detailed walkthrough of bootstrapping a high-availability OKD cluster from physical hardware.
+- [**Deploy a Rust Web App**](./use-cases/deploy-rust-webapp.md): A quick guide to deploying a monitored, containerized web application to a Kubernetes cluster.
+
+## 3. Component Catalogs
+
+Discover existing, reusable components you can use in your Harmony projects.
+
+- [**Scores Catalog**](./catalogs/scores.md): A categorized list of all available `Scores` (the "what").
+- [**Topologies Catalog**](./catalogs/topologies.md): A list of all available `Topologies` (the "where").
+- [**Capabilities Catalog**](./catalogs/capabilities.md): 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**](./guides/writing-a-score.md): Learn how to create your own `Score` and `Interpret` logic to define a new desired state.
+- [**Writing a Topology**](./guides/writing-a-topology.md): Learn how to model a new environment (like AWS, GCP, or custom hardware) as a `Topology`.
+- [**Adding Capabilities**](./guides/adding-capabilities.md): See how to add a `Capability` to your custom `Topology`.

docs/catalogs/README.md

@@ -0,0 +1,7 @@
+# Component Catalogs
+
+This section is the "dictionary" for Harmony. It lists all the reusable components available out-of-the-box.
+
+- [**Scores Catalog**](./scores.md): Discover all available `Scores` (the "what").
+- [**Topologies Catalog**](./topologies.md): A list of all available `Topologies` (the "where").
+- [**Capabilities Catalog**](./capabilities.md): A list of all available `Capabilities` (the "how").

docs/catalogs/capabilities.md

@@ -0,0 +1,40 @@
+# Capabilities Catalog
+
+A `Capability` is a specific feature or API that a `Topology` offers. `Interpret` logic uses these capabilities to execute a `Score`.
+
+This list is primarily for developers **writing new Topologies or Scores**. As a user, you just need to know that the `Topology` you pick (like `K8sAnywhereTopology`) provides the capabilities your `Scores` (like `ApplicationScore`) need.
+
+<!--toc:start-->
+
+- [Capabilities Catalog](#capabilities-catalog)
+  - [Kubernetes & Application](#kubernetes-application)
+  - [Monitoring & Observability](#monitoring-observability)
+  - [Networking (Core Services)](#networking-core-services)
+  - [Networking (Hardware & Host)](#networking-hardware-host)
+
+<!--toc:end-->
+
+## Kubernetes & Application
+
+- **K8sClient**: Provides an authenticated client to interact with a Kubernetes API (create/read/update/delete resources).
+- **HelmCommand**: Provides the ability to execute Helm commands (install, upgrade, template).
+- **TenantManager**: Provides methods for managing tenants in a multi-tenant cluster.
+- **Ingress**: Provides an interface for managing ingress controllers and resources.
+
+## Monitoring & Observability
+
+- **Grafana**: Provides an API for configuring Grafana (datasources, dashboards).
+- **Monitoring**: A general capability for configuring monitoring (e.g., creating Prometheus rules).
+
+## Networking (Core Services)
+
+- **DnsServer**: Provides an interface for creating and managing DNS records.
+- **LoadBalancer**: Provides an interface for configuring a load balancer (e.g., OPNsense, MetalLB).
+- **DhcpServer**: Provides an interface for managing DHCP leases and host bindings.
+- **TftpServer**: Provides an interface for managing files on a TFTP server (e.g., iPXE boot files).
+
+## Networking (Hardware & Host)
+
+- **Router**: Provides an interface for configuring routing rules, typically on a firewall like OPNsense.
+- **Switch**: Provides an interface for configuring a physical network switch (e.g., managing VLANs and port channels).
+- **NetworkManager**: Provides an interface for configuring host-level networking (e.g., creating bonds and bridges on a node).

docs/catalogs/scores.md

@@ -0,0 +1,102 @@
+# Scores Catalog
+
+A `Score` is a declarative description of a desired state. Find the Score you need and add it to your `harmony!` block's `scores` array.
+
+<!--toc:start-->
+
+- [Scores Catalog](#scores-catalog)
+  - [Application Deployment](#application-deployment)
+  - [OKD / Kubernetes Cluster Setup](#okd-kubernetes-cluster-setup)
+  - [Cluster Services & Management](#cluster-services-management)
+  - [Monitoring & Alerting](#monitoring-alerting)
+  - [Infrastructure & Networking (Bare Metal)](#infrastructure-networking-bare-metal)
+  - [Infrastructure & Networking (Cluster)](#infrastructure-networking-cluster)
+  - [Tenant Management](#tenant-management)
+  - [Utility](#utility)
+
+<!--toc:end-->
+
+## Application Deployment
+
+Scores for deploying and managing end-user applications.
+
+- **ApplicationScore**: The primary score for deploying a web application. Describes the application, its framework, and the features it requires (e.g., monitoring, CI/CD).
+- **HelmChartScore**: Deploys a generic Helm chart to a Kubernetes cluster.
+- **ArgoHelmScore**: Deploys an application using an ArgoCD Helm chart.
+- **LAMPScore**: A specialized score for deploying a classic LAMP (Linux, Apache, MySQL, PHP) stack.
+
+## OKD / Kubernetes Cluster Setup
+
+This collection of Scores is used to provision an entire OKD cluster from bare metal. They are typically used in order.
+
+- **OKDSetup01InventoryScore**: Discovers and catalogs the physical hardware.
+- **OKDSetup02BootstrapScore**: Configures the bootstrap node, renders iPXE files, and kicks off the SCOS installation.
+- **OKDSetup03ControlPlaneScore**: Renders iPXE configurations for the control plane nodes.
+- **OKDSetupPersistNetworkBondScore**: Configures network bonds on the nodes and port channels on the switches.
+- **OKDSetup04WorkersScore**: Renders iPXE configurations for the worker nodes.
+- **OKDSetup06InstallationReportScore**: Runs post-installation checks and generates a report.
+- **OKDUpgradeScore**: Manages the upgrade process for an existing OKD cluster.
+
+## Cluster Services & Management
+
+Scores for installing and managing services _inside_ a Kubernetes cluster.
+
+- **K3DInstallationScore**: Installs and configes a local K3D (k3s-in-docker) cluster. Used by `K8sAnywhereTopology`.
+- **CertManagerHelmScore**: Deploys the `cert-manager` Helm chart.
+- **ClusterIssuerScore**: Configures a `ClusterIssuer` for `cert-manager`, (e.g., for Let's Encrypt).
+- **K8sNamespaceScore**: Ensures a Kubernetes namespace exists.
+- **K8sDeploymentScore**: Deploys a generic `Deployment` resource to Kubernetes.
+- **K8sIngressScore**: Configures an `Ingress` resource for a service.
+
+## Monitoring & Alerting
+
+Scores for configuring observability, dashboards, and alerts.
+
+- **ApplicationMonitoringScore**: A generic score to set up monitoring for an application.
+- **ApplicationRHOBMonitoringScore**: A specialized score for setting up monitoring via the Red Hat Observability stack.
+- **HelmPrometheusAlertingScore**: Configures Prometheus alerts via a Helm chart.
+- **K8sPrometheusCRDAlertingScore**: Configures Prometheus alerts using the `PrometheusRule` CRD.
+- **PrometheusAlertScore**: A generic score for creating a Prometheus alert.
+- **RHOBAlertingScore**: Configures alerts specifically for the Red Hat Observability stack.
+- **NtfyScore**: Configures alerts to be sent to a `ntfy.sh` server.
+
+## Infrastructure & Networking (Bare Metal)
+
+Low-level scores for managing physical hardware and network services.
+
+- **DhcpScore**: Configures a DHCP server.
+- **OKDDhcpScore**: A specialized DHCP configuration for the OKD bootstrap process.
+- **OKDBootstrapDhcpScore**: Configures DHCP specifically for the bootstrap node.
+- **DhcpHostBindingScore**: Creates a specific MAC-to-IP binding in the DHCP server.
+- **DnsScore**: Configures a DNS server.
+- **OKDDnsScore**: A specialized DNS configuration for the OKD cluster (e.g., `api.*`, `*.apps.*`).
+- **StaticFilesHttpScore**: Serves a directory of static files (e.g., a documentation site) over HTTP.
+- **TftpScore**: Configures a TFTP server, typically for serving iPXE boot files.
+- **IPxeMacBootFileScore**: Assigns a specific iPXE boot file to a MAC address in the TFTP server.
+- **OKDIpxeScore**: A specialized score for generating the iPXE boot scripts for OKD.
+- **OPNsenseShellCommandScore**: Executes a shell command on an OPNsense firewall.
+
+## Infrastructure & Networking (Cluster)
+
+Network services that run inside the cluster or as part of the topology.
+
+- **LoadBalancerScore**: Configures a general-purpose load balancer.
+- **OKDLoadBalancerScore**: Configures the high-availability load balancers for the OKD API and ingress.
+- **OKDBootstrapLoadBalancerScore**: Configures the load balancer specifically for the bootstrap-time API endpoint.
+- **K8sIngressScore**: Configures an Ingress controller or resource.
+- [HighAvailabilityHostNetworkScore](../../harmony/src/modules/okd/host_network.rs): Configures network bonds on a host and the corresponding port-channels on the switch stack for high-availability.
+
+## Tenant Management
+
+Scores for managing multi-tenancy within a cluster.
+
+- **TenantScore**: Creates a new tenant (e.g., a namespace, quotas, network policies).
+- **TenantCredentialScore**: Generates and provisions credentials for a new tenant.
+
+## Utility
+
+Helper scores for discovery and inspection.
+
+- **LaunchDiscoverInventoryAgentScore**: Launches the agent responsible for the `OKDSetup01InventoryScore`.
+- **DiscoverHostForRoleScore**: A utility score to find a host matching a specific role in the inventory.
+- **InspectInventoryScore**: Dumps the discovered inventory for inspection.

docs/catalogs/topologies.md

@@ -0,0 +1,59 @@
+# Topologies Catalog
+
+A `Topology` is the logical representation of your infrastructure and its `Capabilities`. You select a `Topology` in your Harmony project to define _where_ your `Scores` will be applied.
+
+<!--toc:start-->
+
+- [Topologies Catalog](#topologies-catalog)
+  - [HAClusterTopology](#haclustertopology)
+  - [K8sAnywhereTopology](#k8sanywheretopology)
+
+<!--toc:end-->
+
+### HAClusterTopology
+
+- **`HAClusterTopology::autoload()`**
+
+This `Topology` represents a high-availability, bare-metal cluster. It is designed for production-grade deployments like OKD.
+
+It models an environment consisting of:
+
+- At least 3 cluster nodes (for control plane/workers)
+- 2 redundant firewalls (e.g., OPNsense)
+- 2 redundant network switches
+
+**Provided Capabilities:**
+This topology provides a rich set of capabilities required for bare-metal provisioning and cluster management, including:
+
+- `K8sClient` (once the cluster is bootstrapped)
+- `DnsServer`
+- `LoadBalancer`
+- `DhcpServer`
+- `TftpServer`
+- `Router` (via the firewalls)
+- `Switch`
+- `NetworkManager` (for host-level network config)
+
+---
+
+### K8sAnywhereTopology
+
+- **`K8sAnywhereTopology::from_env()`**
+
+This `Topology` is designed for development and application deployment. It provides a simple, abstract way to deploy to _any_ Kubernetes cluster.
+
+**How it works:**
+
+1. By default (`from_env()` with no env vars), it automatically provisions a **local K3D (k3s-in-docker) cluster** on your machine. This is perfect for local development and testing.
+2. If you provide a `KUBECONFIG` environment variable, it will instead connect to that **existing Kubernetes cluster** (e.g., your staging or production OKD cluster).
+
+This allows you to use the _exact same code_ to deploy your application locally as you do to deploy it to production.
+
+**Provided Capabilities:**
+
+- `K8sClient`
+- `HelmCommand`
+- `TenantManager`
+- `Ingress`
+- `Monitoring`
+- ...and more.

docs/concepts.md

@@ -0,0 +1,40 @@
+# Core Concepts
+
+Harmony's design is based on a few key concepts. Understanding them is the key to unlocking the framework's power.
+
+### 1. Score
+
+- **What it is:** A **Score** is a declarative description of a desired state. It's a "resource" that defines _what_ you want to achieve, not _how_ to do it.
+- **Example:** `ApplicationScore` declares "I want this web application to be running and monitored."
+
+### 2. Topology
+
+- **What it is:** A **Topology** is the logical representation of your infrastructure and its abilities. It's the "where" your Scores will be applied.
+- **Key Job:** A Topology's most important job is to expose which `Capabilities` it supports.
+- **Example:** `HAClusterTopology` represents a bare-metal cluster and exposes `Capabilities` like `NetworkManager` and `Switch`. `K8sAnywhereTopology` represents a Kubernetes cluster and exposes the `K8sClient` `Capability`.
+
+### 3. Capability
+
+- **What it is:** A **Capability** is a specific feature or API that a `Topology` offers. It's the "how" a `Topology` can fulfill a `Score`'s request.
+- **Example:** The `K8sClient` capability offers a way to interact with a Kubernetes API. The `Switch` capability offers a way to configure a physical network switch.
+
+### 4. Interpret
+
+- **What it is:** An **Interpret** is the execution logic that makes a `Score` a reality. It's the "glue" that connects the _desired state_ (`Score`) to the _environment's abilities_ (`Topology`'s `Capabilities`).
+- **How it works:** When you apply a `Score`, Harmony finds the matching `Interpret` for your `Topology`. This `Interpret` then uses the `Capabilities` provided by the `Topology` to execute the necessary steps.
+
+### 5. Inventory
+
+- **What it is:** An **Inventory** is the physical material (the "what") used in a cluster. This is most relevant for bare-metal or on-premise topologies.
+- **Example:** A list of nodes with their roles (control plane, worker), CPU, RAM, and network interfaces. For the `K8sAnywhereTopology`, the inventory might be empty or autoloaded, as the infrastructure is more abstract.
+
+---
+
+### How They Work Together (The Compile-Time Check)
+
+1. You **write a `Score`** (e.g., `ApplicationScore`).
+2. Your `Score`'s `Interpret` logic requires certain **`Capabilities`** (e.g., `K8sClient` and `Ingress`).
+3. You choose a **`Topology`** to run it on (e.g., `HAClusterTopology`).
+4. **At compile-time**, Harmony checks: "Does `HAClusterTopology` provide the `K8sClient` and `Ingress` capabilities that `ApplicationScore` needs?"
+   - **If Yes:** Your code compiles. You can be confident it will run.
+   - **If No:** The compiler gives you an error. You've just prevented a "config-is-valid-but-platform-is-wrong" runtime error before you even deployed.

docs/doc-clone-and-restore-coreos.md

@@ -0,0 +1,133 @@
+## Working procedure to clone and restore CoreOS disk from OKD Cluster
+
+### **Step 1 - take a backup**
+```
+sudo dd if=/dev/old of=/dev/backup status=progress 
+```
+
+### **Step 2 - clone beginning of old disk to new**
+```
+sudo dd if=/dev/old of=/dev/backup status=progress count=1000 bs=1M
+```
+
+### **Step 3 - verify and modify disk partitions**
+list disk partitions
+```
+sgdisk -p /dev/new
+```
+if new disk is smaller than old disk and there is space on the xfs partition of the old disk, modify partitions of new disk
+```
+gdisk /dev/new
+```
+inside of gdisk commands
+```
+-v -> verify table
+-p -> print table
+-d -> select partition to delete partition
+-n -> recreate partition with same partition number as deleted partition
+```
+For end sector, either specify the new end or just press Enter for maximum available 
+When asked about partition type, enter the same type code (it will show the old one) 
+```
+p - >to verify 
+w -> to write
+```
+make xfs file system for new partition <new4>
+```
+sudo mkfs.xfs -f /dev/new4
+```
+
+### **Step 4 - copy old PARTUUID **
+
+**careful here**
+get old patuuid:
+```
+sgdisk -i <partition_number> /dev/old_disk  # Note the "Partition unique GUID"
+```
+get labels
+```
+sgdisk -p /dev/old_disk  # Shows partition names in the table
+
+blkid /dev/old_disk*  # Shows PARTUUIDs and labels for all partitions
+```
+set it on new disk
+```
+sgdisk -u <partition_number>:<old_partuuid> /dev/sdc
+```
+partition name:
+```
+sgdisk -c <partition_number>:"<old_name>" /dev/sdc
+```
+verify all:
+```
+lsblk -o NAME,SIZE,PARTUUID,PARTLABEL /dev/old_disk
+```
+
+### **Step 5 - Mount disks and copy files from old to new disk**
+
+mount files before copy:
+
+```
+mkdir -p /mnt/new
+mkdir -p /mnt/old
+mount /dev/old4 /mnt/old
+mount /dev/new4 /mnt/new
+```
+copy:
+
+with -n flag can run as dry-run
+```
+rsync -aAXHvn --numeric-ids /source/ /destination/
+```
+
+```
+rsync -aAXHv --numeric-ids /source/ /destination/
+```
+
+### **Step 6 - Set correct UUID for new partition 4**
+to set uuid with xfs_admin you must unmount first
+
+unmount old devices
+```
+umount /mnt/new
+umount /mnt/old
+```
+
+to set correct uuid for partition 4
+```
+blkid /dev/old4
+```
+```
+xfs_admin -U <old_uuid> /dev/new_partition
+```
+to set labels
+get it 
+```
+sgdisk -i 4 /dev/sda | grep "Partition name"
+```
+set it
+```
+sgdisk -c 4:"<label_name>" /dev/sdc
+
+or
+
+(check existing with xfs_admin -l /dev/old_partition)
+Use xfs_admin -L <label> /dev/new_partition 
+```
+
+### **Step 7 - Verify**
+
+verify everything:
+```
+sgdisk -p /dev/sda  # Old disk
+sgdisk -p /dev/sdc  # New disk
+```
+```
+lsblk -o NAME,SIZE,PARTUUID,PARTLABEL /dev/sda
+lsblk -o NAME,SIZE,PARTUUID,PARTLABEL /dev/sdc
+```
+```
+blkid /dev/sda* | grep UUID=
+blkid /dev/sdc* | grep UUID=
+```
+

docs/doc-remove-worker-flag.md

@@ -0,0 +1,56 @@
+## **Remove Worker flag from OKD Control Planes** 
+
+### **Context**
+On OKD user provisioned infrastructure the control plane nodes can have the flag node-role.kubernetes.io/worker which allows non critical workloads to be scheduled on the control-planes
+
+### **Observed Symptoms**
+- After adding HAProxy servers to the backend each back end appears down 
+- Traffic is redirected to the control planes instead of workers
+- The pods router-default are incorrectly applied on the control planes rather than on the workers
+- Pods are being scheduled on the control planes causing cluster instability
+
+```
+  ss -tlnp | grep 80
+```
+- shows process haproxy  is listening at 0.0.0.0:80 on cps
+- same problem for port 443
+- In namespace rook-ceph certain pods are deploted on cps rather than on worker nodes
+
+ ### **Cause**
+ - when intalling UPI, the roles (master, worker) are not managed by the Machine Config operator and the cps are made schedulable by default.
+
+ ### **Diagnostic**
+check node labels:
+```
+   oc get nodes --show-labels | grep control-plane
+```
+Inspecter kubelet configuration:
+
+```
+cat /etc/systemd/system/kubelet.service
+```
+
+find the line:
+```
+   --node-labels=node-role.kubernetes.io/control-plane,node-role.kubernetes.io/master,node-role.kubernetes.io/worker
+```
+   → presence of label worker confirms the problem.
+
+Verify the flag doesnt come from MCO
+```
+   oc get machineconfig | grep rendered-master
+```
+
+**Solution:**
+To make the control planes non schedulable you must patch the cluster scheduler resource
+
+```	
+oc patch scheduler cluster --type merge -p '{"spec":{"mastersSchedulable":false}}'
+```
+after the patch is applied the workloads can be deplaced by draining the nodes
+
+```
+oc adm cordon <cp-node>
+oc adm drain <cp-node> --ignore-daemonsets –delete-emptydir-data
+```
+