chore: iobench deployment node example

Reviewed-on: #251

.gitea/workflows/check.yml

@@ -15,4 +15,4 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run check script
-        run: bash check.sh
+        run: bash build/check.sh

.gitignore

@@ -29,3 +29,6 @@ Cargo.lock
 
 # Useful to create ignore folders for temp files and notes
 ignore
+
+# Generated book
+book

Cargo.lock

@@ -249,15 +249,6 @@ dependencies = [
  "zerocopy",
 ]
 
-[[package]]
-name = "aho-corasick"
-version = "0.6.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81ce3d38065e618af2d7b77e10c5ad9a069859b4be3c2250f674af3840d9c8a5"
-dependencies = [
- "memchr",
-]
-
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -297,6 +288,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "ansi_term"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b3568b48b7cefa6b8ce125f9bb4989e52fbcc29ebea88df04cc7c5f12f70455"
+
 [[package]]
 name = "anstream"
 version = "0.6.21"
@@ -686,7 +683,7 @@ dependencies = [
  "tokio-util",
  "tower-service",
  "url",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -718,6 +715,41 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "brocade-snmp-server"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "brocade",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_types",
+ "log",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "brocade-switch"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "brocade",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "serde",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "brotli"
 version = "8.0.2"
@@ -780,12 +812,6 @@ dependencies = [
  "bytes",
 ]
 
-[[package]]
-name = "c_linked_list"
-version = "1.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4964518bd3b4a8190e832886cdc0da9794f12e8e6c1613a9e90ff331c4c8724b"
-
 [[package]]
 name = "camino"
 version = "1.2.2"
@@ -871,6 +897,22 @@ dependencies = [
  "shlex",
 ]
 
+[[package]]
+name = "cert_manager"
+version = "0.1.0"
+dependencies = [
+ "assert_cmd",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -1226,7 +1268,7 @@ dependencies = [
  "parking_lot",
  "signal-hook",
  "signal-hook-mio",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -1242,7 +1284,7 @@ dependencies = [
  "parking_lot",
  "signal-hook",
  "signal-hook-mio",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -1259,7 +1301,7 @@ dependencies = [
  "rustix 0.38.44",
  "signal-hook",
  "signal-hook-mio",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -1268,7 +1310,7 @@ version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
 dependencies = [
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -1669,19 +1711,6 @@ dependencies = [
  "syn 2.0.117",
 ]
 
-[[package]]
-name = "dmidecode"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e529c1bd93d69804dc1e0a0c73aacd12bb13c7a18c659497411abdc6acf5e5f"
-dependencies = [
- "aho-corasick 0.6.10",
- "bitflags 1.3.2",
- "failure",
- "failure_derive",
- "lazy_static",
-]
-
 [[package]]
 name = "dockerfile_builder"
 version = "0.1.6"
@@ -1929,6 +1958,457 @@ dependencies = [
 name = "example"
 version = "0.0.0"
 
+[[package]]
+name = "example-application-monitoring-with-tenant"
+version = "0.1.0"
+dependencies = [
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_types",
+ "logging",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-cli"
+version = "0.1.0"
+dependencies = [
+ "assert_cmd",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-k8s-drain-node"
+version = "0.1.0"
+dependencies = [
+ "assert_cmd",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony-k8s",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "inquire 0.7.5",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-k8s-write-file-on-node"
+version = "0.1.0"
+dependencies = [
+ "assert_cmd",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony-k8s",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "inquire 0.7.5",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-kube-rs"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_macros",
+ "http 1.4.0",
+ "inquire 0.7.5",
+ "k8s-openapi",
+ "kube",
+ "log",
+ "serde_yaml",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-lamp"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-monitoring"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-monitoring-with-tenant"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "harmony",
+ "harmony_cli",
+ "harmony_types",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-multisite-postgres"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-nats"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-nats-module-supercluster"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "k8s-openapi",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-nats-supercluster"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "k8s-openapi",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-node-health"
+version = "0.1.0"
+dependencies = [
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+]
+
+[[package]]
+name = "example-ntfy"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-okd-cluster-alerts"
+version = "0.1.0"
+dependencies = [
+ "brocade",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_secret_derive",
+ "harmony_types",
+ "log",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-okd-install"
+version = "0.1.0"
+dependencies = [
+ "brocade",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_secret_derive",
+ "harmony_types",
+ "log",
+ "schemars 0.8.22",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-openbao"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-operatorhub-catalogsource"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-opnsense"
+version = "0.1.0"
+dependencies = [
+ "brocade",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_types",
+ "log",
+ "schemars 0.8.22",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-opnsense-node-exporter"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_secret_derive",
+ "harmony_types",
+ "log",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-postgresql"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-public-postgres"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-pxe"
+version = "0.1.0"
+dependencies = [
+ "brocade",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_secret_derive",
+ "harmony_types",
+ "log",
+ "schemars 0.8.22",
+ "serde",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-remove-rook-osd"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "tokio",
+]
+
+[[package]]
+name = "example-rust"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-tenant"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-try-rust-webapp"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-tui"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_macros",
+ "harmony_tui",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example-zitadel"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "tokio",
+ "url",
+]
+
+[[package]]
+name = "example_validate_ceph_cluster_health"
+version = "0.1.0"
+dependencies = [
+ "harmony",
+ "harmony_cli",
+ "tokio",
+]
+
 [[package]]
 name = "eyre"
 version = "0.6.12"
@@ -1939,28 +2419,6 @@ dependencies = [
  "once_cell",
 ]
 
-[[package]]
-name = "failure"
-version = "0.1.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d32e9bd16cc02eae7db7ef620b392808b89f6a5e16bb3497d159c6b92a0f4f86"
-dependencies = [
- "backtrace",
- "failure_derive",
-]
-
-[[package]]
-name = "failure_derive"
-version = "0.1.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aa4da3c766cd7a0db8242e326e9e4e081edd567072893ed320008189715366a4"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 1.0.109",
- "synstructure 0.12.6",
-]
-
 [[package]]
 name = "fastrand"
 version = "2.3.0"
@@ -2187,12 +2645,6 @@ dependencies = [
  "byteorder",
 ]
 
-[[package]]
-name = "gcc"
-version = "0.3.55"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f5f3913fa0bfe7ee1fd8248b6b9f42a5af4b9d65ec2dd2c3c26132b950ecfc2"
-
 [[package]]
 name = "generic-array"
 version = "0.14.7"
@@ -2204,28 +2656,6 @@ dependencies = [
  "zeroize",
 ]
 
-[[package]]
-name = "get_if_addrs"
-version = "0.5.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abddb55a898d32925f3148bd281174a68eeb68bbfd9a5938a57b18f506ee4ef7"
-dependencies = [
- "c_linked_list",
- "get_if_addrs-sys",
- "libc",
- "winapi 0.2.8",
-]
-
-[[package]]
-name = "get_if_addrs-sys"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d04f9fb746cf36b191c00f3ede8bde9c8e64f9f4b05ae2694a9ccf5e3f5ab48"
-dependencies = [
- "gcc",
- "libc",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -2540,6 +2970,36 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "harmony_config"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "directories",
+ "harmony_config_derive",
+ "harmony_secret",
+ "inquire 0.7.5",
+ "interactive-parse",
+ "log",
+ "pretty_assertions",
+ "schemars 0.8.22",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tokio",
+]
+
+[[package]]
+name = "harmony_config_derive"
+version = "0.1.0"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "harmony_execution"
 version = "0.1.0"
@@ -2560,7 +3020,7 @@ dependencies = [
  "harmony_types",
  "local-ip-address",
  "log",
- "mdns-sd 0.14.1 (git+https://github.com/jggc/mdns-sd.git?branch=patch-1)",
+ "mdns-sd",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
@@ -2569,6 +3029,19 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "harmony_inventory_builder"
+version = "0.1.0"
+dependencies = [
+ "cidr",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "harmony_macros"
 version = "0.1.0"
@@ -2945,7 +3418,7 @@ dependencies = [
  "pin-project-lite",
  "tokio",
  "tower-service",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -3732,6 +4205,15 @@ dependencies = [
  "log",
 ]
 
+[[package]]
+name = "logging"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "461a8beca676e8ab1bd468c92e9b4436d6368e11e96ae038209e520cfe665e46"
+dependencies = [
+ "ansi_term",
+]
+
 [[package]]
 name = "lru"
 version = "0.12.5"
@@ -3763,36 +4245,6 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "490cc448043f947bae3cbee9c203358d62dbee0db12107a74be5c30ccfd09771"
 
-[[package]]
-name = "mdns"
-version = "0.1.0"
-dependencies = [
- "clap",
- "dmidecode",
- "env_logger",
- "futures",
- "get_if_addrs",
- "local-ip-address",
- "log",
- "mdns-sd 0.14.1 (registry+https://github.com/rust-lang/crates.io-index)",
- "tokio",
-]
-
-[[package]]
-name = "mdns-sd"
-version = "0.14.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e0a59b04e17a195b0674198b3182931801c4759d00f36acad51b5a97210a692"
-dependencies = [
- "fastrand",
- "flume",
- "if-addrs",
- "log",
- "mio 1.1.1",
- "socket-pktinfo",
- "socket2 0.6.3",
-]
-
 [[package]]
 name = "mdns-sd"
 version = "0.14.1"
@@ -3930,7 +4382,7 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3b335231dfd352ffb0f8017f3b6027a4917f7df785ea2143d8af2adc66980ae"
 dependencies = [
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -4831,7 +5283,7 @@ version = "1.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
 dependencies = [
- "aho-corasick 1.1.4",
+ "aho-corasick",
  "memchr",
  "regex-automata",
  "regex-syntax",
@@ -4843,7 +5295,7 @@ version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
 dependencies = [
- "aho-corasick 1.1.4",
+ "aho-corasick",
  "memchr",
  "regex-syntax",
 ]
@@ -4954,6 +5406,21 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "rhob-application-monitoring"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_types",
+ "log",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -5039,7 +5506,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fadd2c0ab350e21c66556f94ee06f766d8bdae3213857ba7610bfd8e10e51880"
 dependencies = [
  "libc",
- "winapi 0.3.9",
+ "winapi",
 ]
 
 [[package]]
@@ -6208,6 +6675,26 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "sttest"
+version = "0.1.0"
+dependencies = [
+ "brocade",
+ "cidr",
+ "env_logger",
+ "harmony",
+ "harmony_cli",
+ "harmony_macros",
+ "harmony_secret",
+ "harmony_secret_derive",
+ "harmony_types",
+ "log",
+ "schemars 0.8.22",
+ "serde",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -7220,12 +7707,6 @@ dependencies = [
  "wasite",
 ]
 
-[[package]]
-name = "winapi"
-version = "0.2.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "167dc9d6949a9b857f3451275e911c3f44255842c1f7a76f33c55103a909087a"
-
 [[package]]
 name = "winapi"
 version = "0.3.9"

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 resolver = "2"
 members = [
+  "examples/*",
   "private_repos/*",
   "harmony",
   "harmony_types",
@@ -15,10 +16,13 @@ members = [
   "harmony_inventory_agent",
   "harmony_secret_derive",
   "harmony_secret",
-  "adr/agent_discovery/mdns",
-   "brocade",
-   "harmony_agent",
-   "harmony_agent/deploy", "harmony_node_readiness", "harmony-k8s",
+  "harmony_config_derive",
+  "harmony_config",
+  "brocade",
+  "harmony_agent",
+  "harmony_agent/deploy",
+  "harmony_node_readiness",
+  "harmony-k8s",
 ]
 
 [workspace.package]

README.md

@@ -1,101 +1,121 @@
 # Harmony
 
-Open-source infrastructure orchestration that treats your platform like first-class code.
+**Infrastructure orchestration that treats your platform like first-class code.**
 
-In other words, Harmony is a **next-generation platform engineering framework**.
+Harmony is an open-source framework that brings the rigor of software engineering to infrastructure management. Write Rust code to define what you want, and Harmony handles the rest — from local development to production clusters.
 
 _By [NationTech](https://nationtech.io)_
 
-[![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/nationtech/harmony)
+[![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)
 
-### Unify
+---
 
-- **Project Scaffolding**
-- **Infrastructure Provisioning**
-- **Application Deployment**
-- **Day-2 operations**
+## The Problem Harmony Solves
 
-All in **one strongly-typed Rust codebase**.
+Modern infrastructure is messy. Your Kubernetes cluster needs monitoring. Your bare-metal servers need provisioning. Your applications need deployments. Each comes with its own tooling, its own configuration format, and its own failure modes.
 
-### Deploy anywhere
+**What if you could describe your entire platform in one consistent language?**
 
-From a **developer laptop** to a **global production cluster**, a single **source of truth** drives the **full software lifecycle.**
+That's Harmony. It unifies project scaffolding, infrastructure provisioning, application deployment, and day-2 operations into a single strongly-typed Rust codebase.
 
-## 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.
+## Three Principles That Make the Difference
 
-| 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 |
+|-----------|---------------|
+| **Infrastructure as Resilient Code** | Stop fighting with YAML and bash. Write type-safe Rust that you can test, version, and refactor like any other code. |
+| **Prove It Works Before You Deploy** | Harmony verifies at _compile time_ that your application can actually run on your target infrastructure. No more "the config looks right but it doesn't work" surprises. |
+| **One Unified Model** | Software and infrastructure are one system. Deploy from laptop to production cluster without switching contexts or tools. |
 
-These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath.
+---
 
-## Where to Start
+## How It Works: The Core Concepts
 
-We have a comprehensive set of documentation right here in the repository.
+Harmony is built around three concepts that work together:
 
-| 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)                      |
+### Score — "What You Want"
 
-## Quick Look: Deploy a Rust Webapp
+A `Score` is a declarative description of desired state. Think of it as a "recipe" that says _what_ you want without specifying _how_ to get there.
 
-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
+// "I want a PostgreSQL cluster running with default settings"
+let postgres = PostgreSQLScore {
+    config: PostgreSQLConfig {
+        cluster_name: "harmony-postgres-example".to_string(),
+        namespace: "harmony-postgres-example".to_string(),
+        ..Default::default()
+    },
+};
+```
+
+### Topology — "Where It Goes"
+
+A `Topology` represents your infrastructure environment and its capabilities. It answers the question: "What can this environment actually do?"
+
+```rust
+// Deploy to a local K3D cluster, or any Kubernetes cluster via environment variables
+K8sAnywhereTopology::from_env()
+```
+
+### Interpret — "How It Happens"
+
+An `Interpret` is the execution logic that connects your `Score` to your `Topology`. It translates "what you want" into "what the infrastructure does."
+
+**The Compile-Time Check:** Before your code ever runs, Harmony verifies that your `Score` is compatible with your `Topology`. If your application needs a feature your infrastructure doesn't provide, you get a compile error — not a runtime failure.
+
+---
+
+## What You Can Deploy
+
+Harmony ships with ready-made Scores for:
+
+**Data Services**
+- PostgreSQL clusters (via CloudNativePG operator)
+- Multi-site PostgreSQL with failover
+
+**Kubernetes**
+- Namespaces, Deployments, Ingress
+- Helm charts
+- cert-manager for TLS
+- Monitoring (Prometheus, alerting, ntfy)
+
+**Bare Metal / Infrastructure**
+- OKD clusters from scratch
+- OPNsense firewalls
+- Network services (DNS, DHCP, TFTP)
+- Brocade switch configuration
+
+**And more:** Application deployment, tenant management, load balancing, and more.
+
+---
+
+## Quick Start: Deploy a PostgreSQL Cluster
+
+This example provisions a local Kubernetes cluster (K3D) and deploys a PostgreSQL cluster on it — no external infrastructure required.
 
 ```rust
 use harmony::{
     inventory::Inventory,
-    modules::{
-        application::{
-            ApplicationScore, RustWebFramework, RustWebapp,
-            features::{PackagingDeployment, rhob_monitoring::Monitoring},
-        },
-        monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
-    },
+    modules::postgresql::{PostgreSQLScore, capability::PostgreSQLConfig},
     topology::K8sAnywhereTopology,
 };
-use harmony_macros::hurl;
-use std::{path::PathBuf, sync::Arc};
 
 #[tokio::main]
 async fn main() {
-    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,
+    let postgres = PostgreSQLScore {
+        config: PostgreSQLConfig {
+            cluster_name: "harmony-postgres-example".to_string(),
+            namespace: "harmony-postgres-example".to_string(),
+            ..Default::default()
+        },
     };
 
     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)],
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(postgres)],
         None,
     )
     .await
@@ -103,40 +123,128 @@ async fn main() {
 }
 ```
 
-To run this:
+### What this actually does
 
-- 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`
+When you compile and run this program:
+
+1. **Compiles** the Harmony Score into an executable
+2. **Connects** to `K8sAnywhereTopology` — which auto-provisions a local K3D cluster if none exists
+3. **Installs** the CloudNativePG operator into the cluster (one-time setup)
+4. **Creates** a PostgreSQL cluster with 1 instance and 1 GiB of storage
+5. **Exposes** the PostgreSQL instance as a Kubernetes Service
+
+### Prerequisites
+
+- [Rust](https://rust-lang.org/tools/install) (edition 2024)
+- [Docker](https://docs.docker.com/get-docker/) (for the local K3D cluster)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (optional, for inspecting the cluster)
+
+### Run it
+
+```bash
+# Clone the repository
+git clone https://git.nationtech.io/nationtech/harmony
+cd harmony
+
+# Build the project
+cargo build --release
+
+# Run the example
+cargo run -p example-postgresql
+```
+
+Harmony will print its progress as it sets up the cluster and deploys PostgreSQL. When complete, you can inspect the deployment:
+
+```bash
+kubectl get pods -n harmony-postgres-example
+kubectl get secret -n harmony-postgres-example harmony-postgres-example-db-user -o jsonpath='{.data.password}' | base64 -d
+```
+
+To connect to the database, forward the port:
+```bash
+kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432
+psql -h localhost -p 5432 -U postgres
+```
+
+To clean up, delete the K3D cluster:
+```bash
+k3d cluster delete harmony-postgres-example
+```
+
+---
+
+## Environment Variables
+
+`K8sAnywhereTopology::from_env()` reads the following environment variables to determine where and how to connect:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KUBECONFIG` | `~/.kube/config` | Path to your kubeconfig file |
+| `HARMONY_AUTOINSTALL` | `true` | Auto-provision a local K3D cluster if none found |
+| `HARMONY_USE_LOCAL_K3D` | `true` | Always prefer local K3D over remote clusters |
+| `HARMONY_PROFILE` | `dev` | Deployment profile: `dev`, `staging`, or `prod` |
+| `HARMONY_K8S_CONTEXT` | _none_ | Use a specific kubeconfig context |
+| `HARMONY_PUBLIC_DOMAIN` | _none_ | Public domain for ingress endpoints |
+
+To connect to an existing Kubernetes cluster instead of provisioning K3D:
+
+```bash
+# Point to your kubeconfig
+export KUBECONFIG=/path/to/your/kubeconfig
+export HARMONY_USE_LOCAL_K3D=false
+export HARMONY_AUTOINSTALL=false
+
+# Then run
+cargo run -p example-postgresql
+```
+
+---
 
 ## Documentation
 
-All documentation is in the `/docs` directory.
+| I want to... | Start here |
+|--------------|------------|
+| Understand the core concepts | [Core Concepts](./docs/concepts.md) |
+| Deploy my first application | [Getting Started Guide](./docs/guides/getting-started.md) |
+| Explore available components | [Scores Catalog](./docs/catalogs/scores.md) · [Topologies Catalog](./docs/catalogs/topologies.md) |
+| See a complete bare-metal deployment | [OKD on Bare Metal](./docs/use-cases/okd-on-bare-metal.md) |
+| Build my own Score or Topology | [Developer Guide](./docs/guides/developer-guide.md) |
 
-- [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.
+---
 
-## Architectural Decision Records
+## Why Rust?
 
-- [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)
+We chose Rust for the same reason you might: **reliability through type safety**.
 
-## Contribute
+Infrastructure code runs in production. It needs to be correct. Rust's ownership model and type system let us build a framework where:
 
-Discussions and roadmap live in [Issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
+- Invalid configurations fail at compile time, not at 3 AM
+- Refactoring infrastructure is as safe as refactoring application code
+- The compiler verifies that your platform can actually fulfill your requirements
+
+See [ADR-001 · Why Rust](./adr/001-rust.md) for our full rationale.
+
+---
+
+## Architecture Decisions
+
+Harmony's design is documented through Architecture Decision Records (ADRs):
+
+- [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)
+
+---
 
 ## License
 
 Harmony is released under the **GNU AGPL v3**.
 
-> We choose a strong copyleft license to ensure the project—and every improvement to it—remains open and benefits the entire community. Fork it, enhance it, even out-innovate us; just keep it open.
+> We choose a strong copyleft license to ensure the project—and every improvement to it—remains open and benefits the entire community.
 
 See [LICENSE](LICENSE) for the full text.
 
 ---
 
-_Made with ❤️ & 🦀 by the NationTech and the Harmony community_
+_Made with ❤️ & 🦀 by NationTech and the Harmony community_

adr/014-infrastructure-network-ports.md

@@ -0,0 +1,124 @@
+# ADR‑014 · Port Allocation Policy
+
+**Date:** 2025‑11‑03  
+**Status:** Proposed  
+**Authors:** Infrastructure Team / NationTech Harmony Core  
+
+---
+
+## 1 · Context
+
+Harmony orchestrates heterogeneous clusters — from developer laptops to multi‑tenant production environments — through a single, typed Rust codebase.  
+To enable deterministic, automatable service exposure across clusters, we need a **stable, conflict‑free range of TCP/UDP ports** reserved for Harmony‑managed workloads and host‑network services.
+
+Today, various manual operations (e.g. Ceph RGW on host network) occasionally use ad‑hoc local ports such as `80` or `8080`. This leads to unpredictable overlaps with NodePorts, ephemeral ports, or other daemons.
+
+Since Harmony aims to unify *manual* and *automated* infrastructure under a single declarative model, we formalize a **reserved port block** that should be used consistently — even for out‑of‑band operations — so everything remains alignment‑ready for future orchestration.
+
+---
+
+## 2 · Problem Statement
+
+We must select a contiguous range of approximately 1000 ports that:
+
+1. Avoids conflict with:
+   - System / well‑known ports (`0–1023`)
+   - Common registered application ports (`1024–49151`)
+   - Kubernetes NodePort default range (`30 000–32 767`)
+   - Ephemeral port ranges (typically `32 768–60 999` on Linux)
+2. Feels deterministic and maintainable for long‑term automation.
+3. Can be mirrored across multiple clusters and bare‑metal hosts.
+
+---
+
+## 3 · Decision
+
+We designate:
+
+> **Harmony Reserved Port Range:** `25 000 – 25 999`
+
+### Rationale
+
+| Criterion | Reasoning |
+|------------|------------|
+| **Safety** | Lies below the default ephemeral port start (`32 768`) and above NodePort (`30 000–32 767`). |
+| **Conflicts** | Very few historical IANA registrations in this span, practically unused in modern systems. |
+| **Predictability** | Easy to recognize and communicate (`25k‑block` for Harmony). |
+| **Ergonomics** | Mirrors production service conventions (`25080` for HTTP‑like, `25443` for HTTPS‑like, etc.). |
+| **Cross‑cluster consistency** | Portable across OKD, K3D, bare‑metal – allows static firewall rules. |
+
+This range is *registered* (per IANA definition 1024–49151) but not *occupied*. Choosing such a mid‑registered band is intentional: it guarantees good inter‑platform compatibility without interfering with OS‑managed ephemeral allocations.
+
+---
+
+## 4 · Integration in Harmony
+
+Harmony’s topology and orchestration layers should expose a built‑in **`PortAllocator`** resource:
+
+```rust
+let orchestrator_ports = harmony::network::PortAllocator::new(25_000, 25_999);
+let rados_gateway_port = orchestrator_ports.allocate("ceph-rgw")?;
+```
+
+In TOML configuration:
+
+```toml
+[harmony.network.defaults]
+orchestrator_port_range = "25000-25999"
+```
+
+All `Score` / `Interpret` modules that deploy host‑network or externally visible services should use this allocator to pick ports deterministically.
+
+---
+
+## 5 · Operational Guidance
+
+- **Manual Operations:** Even manually configured host‑network services on clusters we manage (e.g. Ceph RGW, ntfy, reverse proxy tests) should adopt ports within `25 000–25 999`.
+- **Automation Alignment:** Any such ports are considered *Harmony‑manageable* and may be introspected later by the orchestrator.
+- **Firewall Rules:** Cluster and site firewalls may pre‑whitelist this block as “Harmony Infra Ports”.
+
+---
+
+## 6 · Initial Allocation Table
+
+| Service / Component | Port | Notes |
+|----------------------|------|-------|
+| **Ceph RADOS Gateway** | **25080** | Replacement for `:80`; public HTTP front‑end via RGW (host network). |
+| **Internal HTTPS Services** | 25443 | Equivalent of `:443` for secure endpoints. |
+| **Prometheus / Metrics Endpoints** | 25090–25099 | Internal observability. |
+| **Harmony Control Plane (gRPC)** | 25500–25519 | Inter‑process messaging, API, TUI backend. |
+| **Reserved for Future Scores** | 25550–25599 | Dedicated expansion slots. |
+
+These values shall be managed centrally in a `harmony.network.ports` registry file (YAML / TOML) within the repository.
+
+---
+
+## 7 · Consequences
+
+### Positive
+- Eliminates accidental collisions with NodePorts and ephemeral connections.
+- Provides a memorable, human‑readable convention suitable for documentation and automation.
+- Enables Harmony to treat host‑network configuration as first‑class code.
+
+### Negative / Trade‑offs
+- Occupies part of the IANA “registered” band (must remain consistent across environments).
+- Requires operators to adapt legacy services away from lower ports (`80`, `443`) for compliance with this policy.
+
+---
+
+## 8 · Future Work
+- Extend Harmony CLI to display currently allocated ports and detect conflicts.  
+- Expose a compile‑time capability check ensuring clusters in a topology do not re‑use the same port twice.  
+- Consider parallel UDP range reservation when we start exposing datagram services.  
+
+---
+
+## 9 · References
+- [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)  
+- [Kubernetes NodePort default range documentation](https://kubernetes.io/docs/concepts/services-networking/service/)  
+- Harmony ADR‑001 · Why Rust  
+- Harmony ADR‑003 · Infrastructure Abstractions  
+
+---
+
+*Made with 🦀 by the NationTech Harmony team — ensuring your infrastructure behaves like code.*

adr/017-3-revised-staleness-detection-algorithm-inspired-by-kubernetes.md

@@ -0,0 +1,107 @@
+### Context & Use Case
+We are implementing a High Availability (HA) Failover Strategy for decentralized "Micro Data Centers." The core challenge is managing stateful workloads (PostgreSQL) over unreliable networks.
+
+We solve this using a **Local Fencing First** approach, backed by **NATS JetStream Strict Ordering** for the final promotion authority.
+
+In CAP theorem terms, we are developing a CP system, intentionally sacrificing availability. In practical terms, we expect an average of two primary outages per year, with a failover delay of around 2 minutes. This translates to an uptime of over five nines. To be precise, 2 outages * 2 minutes = 4 minutes per year = 99.99924% uptime.
+
+### The Algorithm: Local Fencing & Remote Promotion
+
+The safety (data consistency) of the system relies on the time gap between the **Primary giving up (Fencing)** and the **Replica taking over (Promotion)**.
+
+To avoid clock skew issues between agents and datastore (nats), all timestamps comparisons will be done using jetstream metadata. I.E. a harmony agent will never use `Instant::now()` to get a timestamp, it will use `my_last_heartbeat.metadata.timestamp` (conceptually).
+
+#### 1. Configuration
+*   `heartbeat_timeout` (e.g., 1s): Max time allowed for a NATS write/DB check.
+*   `failure_threshold` (e.g., 2): Consecutive failures before self-fencing.
+*   `failover_timeout` (e.g., 5s): Time since last NATS update of Primary heartbeat before Replica promotes.
+    * This timeout must be carefully configured to allow enough time for the primary to fence itself (after `heartbeat_timeout * failure_threshold`) BEFORE the replica gets promoted to avoid a split brain with two primaries.
+        * Implementing this will rely on the actual deployment configuration. For example, a CNPG based PostgreSQL cluster might require a longer gap (such as 30s) than other technologies.
+    * Expires when `replica_heartbeat.metadata.timestamp - primary_heartbeat.metadata.timestamp > failover_timeout`
+
+#### 2. The Primary (Self-Preservation)
+
+The Primary is aggressive about killing itself.
+
+*   It attempts a heartbeat.
+*   If the network latency > `heartbeat_timeout`, the attempt is **cancelled locally** because the heartbeat did not make it back in time.
+*   This counts as a failure and increments the `consecutive_failures` counter.
+*   If `consecutive_failures` hit the threshold, **FENCING occurs immediately**. The database is stopped.
+
+This means that the Primary will fence itself after `heartbeat_timeout * failure_threshold`.
+
+#### 3. The Replica (The Watchdog)
+
+The Replica is patient.
+
+*   It watches the NATS stream to measure if `replica_heartbeat.metadata.timestamp - primary_heartbeat.metadata.timestamp > failover_timeout`
+*   It only attempts promotion if the `failover_timeout` (5s) has passed.
+*   **Crucial:** Careful configuration of the failover_timeout is required. This is the only way to avoid a split brain in case of a network partition where the Primary cannot write its heartbeats in time anymore.
+    * In short, `failover_timeout` should be tuned to be `heartbeat_timeout * failure_threshold + safety_margin`. This `safety_margin` will vary by use case. For example, a CNPG cluster may need 30 seconds to demote a Primary to Replica when fencing is triggered, so `safety_margin` should be at least 30s in that setup.
+
+Since we forcibly fail timeouts after `heartbeat_timeout`, we are guaranteed that the primary will have **started** the fencing process after `heartbeat_timeout * failure_threshold`.
+
+But, in a network split scenario where the failed primary is still accessible by clients but cannot write its heartbeat successfully, there is no way to know if the demotion has actually **completed**.
+
+For example, in a CNPG cluster, the failed Primary agent will attempt to change the CNPG cluster state to read-only. But if anything fails after that attempt (permission error, k8s api failure, CNPG bug, etc) it is possible that the PostgreSQL instance keeps accepting writes.
+
+While this is not a theoretical failure of the agent's algorithm, this is a practical failure where data corruption occurs.
+
+This can be fixed by detecting the demotion failure and escalating the fencing procedure aggressiveness. Harmony being an infrastructure orchestrator, it can easily exert radical measures if given the proper credentials, such as forcibly powering off a server, disconnecting its network in the switch configuration, forcibly kill a pod/container/process, etc.
+
+However, these details are out of scope of this algorithm, as they simply fall under the "fencing procedure".
+
+The implementation of the fencing procedure itself is not relevant. This algorithm's responsibility stops at calling the fencing procedure in the appropriate situation.
+
+#### 4. The Demotion Handshake (Return to Normalcy)
+
+When the original Primary recovers:
+
+1.  It becomes healthy locally but sees `current_primary = Replica`. It waits.
+2.  The Replica (current leader) detects the Original Primary is back (via NATS heartbeats).
+3.  Replica performs a **Clean Demotion**:
+    *   Stops DB.
+    *   Writes `current_primary = None` to NATS.
+4.  Original Primary sees `current_primary = None` and can launch the promotion procedure.
+
+Depending on the implementation, the promotion procedure may require a transition phase. Typically, for a PostgreSQL use case the promoting primary will make sure it has caught up on WAL replication before starting to accept writes.
+
+---
+
+### Failure Modes & Behavior Analysis
+
+#### Case 1: Immediate Outage (Power Cut)
+
+*   **Primary:** Dies instantly. Fencing is implicit (machine is off).
+*   **Replica:** Waits for `failover_timeout` (5s). Sees staleness. Promotes self.
+*   **Outcome:** Clean failover after 5s.
+
+// TODO detail what happens when the primary comes back up. We will likely have to tie PostgreSQL's lifecycle (liveness/readiness probes) with the agent to ensure it does not come back up as primary.
+
+#### Case 2: High Network Latency on the Primary (The "Split Brain" Trap)
+
+*   **Scenario:** Network latency spikes to 5s on the Primary, still below `heartbeat_timeout` on the Replica.
+*   **T=0 to T=2 (Primary):** Tries to write. Latency (5s) > Timeout (1s). Fails twice.
+*   **T=2 (Primary):** `consecutive_failures` = 2. **Primary Fences Self.** (Service is DOWN).
+*   **T=2 to T=5 (Cluster):** **Read-Only Phase.** No Primary exists.
+*   **T=5 (Replica):** `failover_timeout` reached. Replica promotes self.
+*   **Outcome:** Safe failover. The "Read-Only Gap" (T=2 to T=5) ensures no Split Brain occurred.
+
+#### Case 3: Replica Network Lag (False Positive)
+
+*   **Scenario:** Replica has high latency, greater than `failover_timeout`; Primary is fine.
+*   **Replica:** Thinks Primary is dead. Tries to promote by setting `cluster_state.current_primary = replica_id`.
+*   **NATS:** Rejects the write because the Primary is still updating the sequence numbers successfully.
+*   **Outcome:** Promotion denied. Primary stays leader.
+
+#### Case 4: Network Instability (Flapping)
+
+*   **Scenario:** Intermittent packet loss.
+*   **Primary:** Fails 1 heartbeat, succeeds the next. `consecutive_failures` resets.
+*   **Replica:** Sees a slight delay in updates, but never reaches `failover_timeout`.
+*   **Outcome:** No Fencing, No Promotion. System rides out the noise.
+
+## Contextual notes
+
+* Clock skew : Tokio relies on monotonic clocks. This means that `tokio::time::sleep(...)` will not be affected by system clock corrections (such as NTP). But monotonic clocks are known to jump forward in some cases such as VM live migrations. This could mean a false timeout of a single heartbeat. If `failure_threshold = 1`, this can mean a false negative on the nodes' health, and a potentially useless demotion.
+

adr/017-3-revised-staleness-detection-algorithm-inspired-by-kubernetes.md.txt

@@ -0,0 +1,107 @@
+### Context & Use Case
+We are implementing a High Availability (HA) Failover Strategy for decentralized "Micro Data Centers." The core challenge is managing stateful workloads (PostgreSQL) over unreliable networks.
+
+We solve this using a **Local Fencing First** approach, backed by **NATS JetStream Strict Ordering** for the final promotion authority.
+
+In CAP theorem terms, we are developing a CP system, intentionally sacrificing availability. In practical terms, we expect an average of two primary outages per year, with a failover delay of around 2 minutes. This translates to an uptime of over five nines. To be precise, 2 outages * 2 minutes = 4 minutes per year = 99.99924% uptime.
+
+### The Algorithm: Local Fencing & Remote Promotion
+
+The safety (data consistency) of the system relies on the time gap between the **Primary giving up (Fencing)** and the **Replica taking over (Promotion)**.
+
+To avoid clock skew issues between agents and datastore (nats), all timestamps comparisons will be done using jetstream metadata. I.E. a harmony agent will never use `Instant::now()` to get a timestamp, it will use `my_last_heartbeat.metadata.timestamp` (conceptually).
+
+#### 1. Configuration
+*   `heartbeat_timeout` (e.g., 1s): Max time allowed for a NATS write/DB check.
+*   `failure_threshold` (e.g., 2): Consecutive failures before self-fencing.
+*   `failover_timeout` (e.g., 5s): Time since last NATS update of Primary heartbeat before Replica promotes.
+    * This timeout must be carefully configured to allow enough time for the primary to fence itself (after `heartbeat_timeout * failure_threshold`) BEFORE the replica gets promoted to avoid a split brain with two primaries.
+        * Implementing this will rely on the actual deployment configuration. For example, a CNPG based PostgreSQL cluster might require a longer gap (such as 30s) than other technologies.
+    * Expires when `replica_heartbeat.metadata.timestamp - primary_heartbeat.metadata.timestamp > failover_timeout`
+
+#### 2. The Primary (Self-Preservation)
+
+The Primary is aggressive about killing itself.
+
+*   It attempts a heartbeat.
+*   If the network latency > `heartbeat_timeout`, the attempt is **cancelled locally** because the heartbeat did not make it back in time.
+*   This counts as a failure and increments the `consecutive_failures` counter.
+*   If `consecutive_failures` hit the threshold, **FENCING occurs immediately**. The database is stopped.
+
+This means that the Primary will fence itself after `heartbeat_timeout * failure_threshold`.
+
+#### 3. The Replica (The Watchdog)
+
+The Replica is patient.
+
+*   It watches the NATS stream to measure if `replica_heartbeat.metadata.timestamp - primary_heartbeat.metadata.timestamp > failover_timeout`
+*   It only attempts promotion if the `failover_timeout` (5s) has passed.
+*   **Crucial:** Careful configuration of the failover_timeout is required. This is the only way to avoid a split brain in case of a network partition where the Primary cannot write its heartbeats in time anymore.
+    * In short, `failover_timeout` should be tuned to be `heartbeat_timeout * failure_threshold + safety_margin`. This `safety_margin` will vary by use case. For example, a CNPG cluster may need 30 seconds to demote a Primary to Replica when fencing is triggered, so `safety_margin` should be at least 30s in that setup.
+
+Since we forcibly fail timeouts after `heartbeat_timeout`, we are guaranteed that the primary will have **started** the fencing process after `heartbeat_timeout * failure_threshold`.
+
+But, in a network split scenario where the failed primary is still accessible by clients but cannot write its heartbeat successfully, there is no way to know if the demotion has actually **completed**.
+
+For example, in a CNPG cluster, the failed Primary agent will attempt to change the CNPG cluster state to read-only. But if anything fails after that attempt (permission error, k8s api failure, CNPG bug, etc) it is possible that the PostgreSQL instance keeps accepting writes.
+
+While this is not a theoretical failure of the agent's algorithm, this is a practical failure where data corruption occurs.
+
+This can be fixed by detecting the demotion failure and escalating the fencing procedure aggressiveness. Harmony being an infrastructure orchestrator, it can easily exert radical measures if given the proper credentials, such as forcibly powering off a server, disconnecting its network in the switch configuration, forcibly kill a pod/container/process, etc.
+
+However, these details are out of scope of this algorithm, as they simply fall under the "fencing procedure".
+
+The implementation of the fencing procedure itself is not relevant. This algorithm's responsibility stops at calling the fencing procedure in the appropriate situation.
+
+#### 4. The Demotion Handshake (Return to Normalcy)
+
+When the original Primary recovers:
+
+1.  It becomes healthy locally but sees `current_primary = Replica`. It waits.
+2.  The Replica (current leader) detects the Original Primary is back (via NATS heartbeats).
+3.  Replica performs a **Clean Demotion**:
+    *   Stops DB.
+    *   Writes `current_primary = None` to NATS.
+4.  Original Primary sees `current_primary = None` and can launch the promotion procedure.
+
+Depending on the implementation, the promotion procedure may require a transition phase. Typically, for a PostgreSQL use case the promoting primary will make sure it has caught up on WAL replication before starting to accept writes.
+
+---
+
+### Failure Modes & Behavior Analysis
+
+#### Case 1: Immediate Outage (Power Cut)
+
+*   **Primary:** Dies instantly. Fencing is implicit (machine is off).
+*   **Replica:** Waits for `failover_timeout` (5s). Sees staleness. Promotes self.
+*   **Outcome:** Clean failover after 5s.
+
+// TODO detail what happens when the primary comes back up. We will likely have to tie PostgreSQL's lifecycle (liveness/readiness probes) with the agent to ensure it does not come back up as primary.
+
+#### Case 2: High Network Latency on the Primary (The "Split Brain" Trap)
+
+*   **Scenario:** Network latency spikes to 5s on the Primary, still below `heartbeat_timeout` on the Replica.
+*   **T=0 to T=2 (Primary):** Tries to write. Latency (5s) > Timeout (1s). Fails twice.
+*   **T=2 (Primary):** `consecutive_failures` = 2. **Primary Fences Self.** (Service is DOWN).
+*   **T=2 to T=5 (Cluster):** **Read-Only Phase.** No Primary exists.
+*   **T=5 (Replica):** `failover_timeout` reached. Replica promotes self.
+*   **Outcome:** Safe failover. The "Read-Only Gap" (T=2 to T=5) ensures no Split Brain occurred.
+
+#### Case 3: Replica Network Lag (False Positive)
+
+*   **Scenario:** Replica has high latency, greater than `failover_timeout`; Primary is fine.
+*   **Replica:** Thinks Primary is dead. Tries to promote by setting `cluster_state.current_primary = replica_id`.
+*   **NATS:** Rejects the write because the Primary is still updating the sequence numbers successfully.
+*   **Outcome:** Promotion denied. Primary stays leader.
+
+#### Case 4: Network Instability (Flapping)
+
+*   **Scenario:** Intermittent packet loss.
+*   **Primary:** Fails 1 heartbeat, succeeds the next. `consecutive_failures` resets.
+*   **Replica:** Sees a slight delay in updates, but never reaches `failover_timeout`.
+*   **Outcome:** No Fencing, No Promotion. System rides out the noise.
+
+## Contextual notes
+
+* Clock skew : Tokio relies on monotonic clocks. This means that `tokio::time::sleep(...)` will not be affected by system clock corrections (such as NTP). But monotonic clocks are known to jump forward in some cases such as VM live migrations. This could mean a false timeout of a single heartbeat. If `failure_threshold = 1`, this can mean a false negative on the nodes' health, and a potentially useless demotion.
+

adr/017-Multi-Cluster-Federation-And-Granular-Authorization.md

@@ -0,0 +1,84 @@
+# ADR 017: Multi-Cluster Federation and Granular Authorization
+
+*   **Status:** Accepted
+*   **Date:** 2025-12-20
+*   **Context:** ADR-016 Harmony Agent and Global Mesh For Decentralized Workload Management
+
+## Context and Problem Statement
+
+As Harmony expands to manage workloads across multiple independent clusters, we face two specific requirements regarding network topology and security:
+
+1.  **Granular Authorization:** We need the ability to authorize a specific node (Leaf Node) from the decentralized mesh to access only a specific subset of topics within a cluster. For example, a collaborator connecting to our Public Cloud should not have visibility into other collaborator's data or our internal system events. Same goes the other way, when we connect to a collaborator cluster, we must not gain access to their internal data.
+2.  **Hybrid/Failover Topologies:** Users need to run their own private meshes (e.g., 5 interconnected office locations) with full internal trust, while simultaneously maintaining a connection to the Harmony Public Cloud for failover or bursting. In this scenario, the Public Cloud must not have access to the private mesh's internal data, and the private mesh should only access specific "public" topics on the cloud.
+
+We need to decide how the Harmony Agent and the underlying NATS infrastructure will handle these "Split-Horizon" and "Zero-Trust" scenarios without complicating the application logic within the Agent itself.
+
+## Decision Drivers
+
+*   **Security:** Default-deny posture is required for cross-domain connections.
+*   **Isolation:** Private on-premise clusters must remain private; data leakage to the public cloud is unacceptable.
+*   **Simplicity:** The Harmony Agent code should not be burdened with managing multiple complex TCP connections or application-layer routing logic.
+*   **Efficiency:** Failover traffic should only occur when necessary; network chatter (gossip) from the Public Cloud should not propagate to private nodes.
+
+## Considered Options
+
+1.  **Application-Layer Multi-Homing:** The Harmony Agent maintains two distinct active connections (one to Local, one to Cloud) and handles routing logic in Go code.
+2.  **VPN/VPC Peering:** Connect private networks to the public cloud at the network layer (IPSec/WireGuard).
+3.  **NATS Account Federation & Leaf Nodes:** Utilize NATS native multi-tenancy (Accounts) and topology bridging (Leaf Nodes) to handle routing and permissions at the protocol layer.
+
+## Decision Outcome
+
+We will adopt **Option 3: NATS Account Federation & Leaf Nodes**.
+
+We will leverage NATS built-in "Accounts" to create logical isolation boundaries and "Service Imports/Exports" to bridge specific data streams between private and public clusters.
+
+### 1. Authorization Strategy (Subject-Based Permissions)
+
+We will not implement custom authorization logic inside the Harmony Agent for topic access. Instead, we will enforce **Subject-Based Permissions** at the NATS server level.
+
+*   **Mechanism:** When a Leaf Node (e.g., a Customer Site) connects to the Public Cloud, it must authenticate using a scoped credential (JWT/NKey).
+*   **Policy:** This credential will carry a permission policy that strictly defines:
+    *   `PUB`: Allowed subjects (e.g., `harmony.public.requests`).
+    *   `SUB`: Allowed subjects (e.g., `harmony.public.responses`).
+    *   `DENY`: Implicitly everything else (including `_SYS.>`, other customer streams).
+*   **Enforcement:** The NATS server rejects unauthorized subscriptions or publications at the protocol level before they reach the application layer.
+
+### 2. Hybrid Topology Strategy (Federation)
+
+We will use **NATS Account Federation** to solve the "Hybrid Cloud" requirement. We will treat the Private Mesh and Public Cloud as separate "Accounts."
+
+*   **The Private Mesh (Business Account):**
+    *   Consists of the customer's internal nodes (e.g., 5 locations).
+    *   Nodes share full trust and visibility of `local.*` subjects.
+    *   Configured as a **Leaf Node** connection to the Public Cloud.
+*   **The Public Cloud (SaaS Account):**
+    *   **Exports** a specific stream/service (e.g., `public.compute.rentals`).
+    *   Does *not* join the customer's cluster mesh. It acts as a hub.
+*   **The Bridge (Import):**
+    *   The Private Mesh **Imports** the public stream.
+    *   The Private Mesh maps this import to a local subject, e.g., `external.cloud`.
+
+### 3. Failover Logic
+
+The Harmony Agent will implement failover by selecting the target subject, relying on NATS to route the message physically.
+
+1.  **Primary Attempt:** Agent publishes to `local.compute`. NATS routes this only to the 5 internal sites.
+2.  **Failover Condition:** If internal capacity is exhausted (determined by Agent heuristics), the Agent publishes to `external.cloud`.
+3.  **Routing:** NATS transparently routes `external.cloud` messages over the Leaf Node connection to the Public Cloud.
+4.  **Security:** Because the Public Cloud does not import `local.compute`, it never sees internal traffic.
+
+## Consequences
+
+### Positive
+*   **Zero-Trust by Design:** The Public Cloud cannot spy on the Private Mesh because no streams are exported from Private to Public.
+*   **Reduced Complexity:** The Harmony Agent remains simple; it just publishes to different topics. It does not need to manage connection pools or complex authentication handshakes for multiple clouds.
+*   **Bandwidth Efficiency:** Gossip protocol traffic (cluster topology updates) is contained within the Accounts. The Private Mesh does not receive heartbeat traffic from the massive Public Cloud.
+
+### Negative
+*   **Configuration Overhead:** Setting up NATS Accounts, Imports, and Exports requires more complex configuration files (server.conf) and understanding of JWT/NKeys compared to a flat mesh.
+*   **Observability:** Tracing a message as it crosses Account boundaries (from Private `external.cloud` to Public `public.compute`) requires centralized monitoring that understands Federation.
+
+## References
+*   [NATS Documentation: Subject-Based Access Control](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/subject_access)
+*   [NATS Documentation: Leaf Nodes](https://docs.nats.io/running-a-nats-service/configuration/leafnodes)
+*   [NATS Documentation: Services & Streams (Imports/Exports)](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/accounts)

adr/020-monitoring-alerting-architecture.md

@@ -1,318 +0,0 @@
-# Architecture Decision Record: Monitoring and Alerting Architecture
-
-Initial Author: Willem Rolleman, Jean-Gabriel Carrier
-
-Initial Date: March 9, 2026
-
-Last Updated Date: March 9, 2026
-
-## Status
-
-Accepted
-
-Supersedes: [ADR-010](010-monitoring-and-alerting.md)
-
-## Context
-
-Harmony needs a unified approach to monitoring and alerting across different infrastructure targets:
-
-1. **Cluster-level monitoring**: Administrators managing entire Kubernetes/OKD clusters need to define cluster-wide alerts, receivers, and scrape targets.
-
-2. **Tenant-level monitoring**: Multi-tenant clusters where teams are confined to namespaces need monitoring scoped to their resources.
-
-3. **Application-level monitoring**: Developers deploying applications want zero-config monitoring that "just works" for their services.
-
-The monitoring landscape is fragmented:
-- **OKD/OpenShift**: Built-in Prometheus with AlertmanagerConfig CRDs
-- **KubePrometheus**: Helm-based stack with PrometheusRule CRDs
-- **RHOB (Red Hat Observability)**: Operator-based with MonitoringStack CRDs
-- **Standalone Prometheus**: Raw Prometheus deployments
-
-Each system has different CRDs, different installation methods, and different configuration APIs.
-
-## Decision
-
-We implement a **trait-based architecture with compile-time capability verification** that provides:
-
-1. **Type-safe abstractions** via parameterized traits: `AlertReceiver<S>`, `AlertRule<S>`, `ScrapeTarget<S>`
-2. **Compile-time topology compatibility** via the `Observability<S>` capability bound
-3. **Three levels of abstraction**: Cluster, Tenant, and Application monitoring
-4. **Pre-built alert rules** as functions that return typed structs
-
-### Core Traits
-
-```rust
-// domain/topology/monitoring.rs
-
-/// Marker trait for systems that send alerts (Prometheus, etc.)
-pub trait AlertSender: Send + Sync + std::fmt::Debug {
-    fn name(&self) -> String;
-}
-
-/// Defines how a receiver (Discord, Slack, etc.) builds its configuration
-/// for a specific sender type
-pub trait AlertReceiver<S: AlertSender>: std::fmt::Debug + Send + Sync {
-    fn build(&self) -> Result<ReceiverInstallPlan, InterpretError>;
-    fn name(&self) -> String;
-    fn clone_box(&self) -> Box<dyn AlertReceiver<S>>;
-}
-
-/// Defines how an alert rule builds its PrometheusRule configuration
-pub trait AlertRule<S: AlertSender>: std::fmt::Debug + Send + Sync {
-    fn build_rule(&self) -> Result<serde_json::Value, InterpretError>;
-    fn name(&self) -> String;
-    fn clone_box(&self) -> Box<dyn AlertRule<S>>;
-}
-
-/// Capability that topologies implement to support monitoring
-pub trait Observability<S: AlertSender> {
-    async fn install_alert_sender(&self, sender: &S, inventory: &Inventory) 
-        -> Result<PreparationOutcome, PreparationError>;
-    async fn install_receivers(&self, sender: &S, inventory: &Inventory, 
-        receivers: Option<Vec<Box<dyn AlertReceiver<S>>>>) -> Result<...>;
-    async fn install_rules(&self, sender: &S, inventory: &Inventory,
-        rules: Option<Vec<Box<dyn AlertRule<S>>>>) -> Result<...>;
-    async fn add_scrape_targets(&self, sender: &S, inventory: &Inventory,
-        scrape_targets: Option<Vec<Box<dyn ScrapeTarget<S>>>>) -> Result<...>;
-    async fn ensure_monitoring_installed(&self, sender: &S, inventory: &Inventory) 
-        -> Result<...>;
-}
-```
-
-### Alert Sender Types
-
-Each monitoring stack is a distinct `AlertSender`:
-
-| Sender | Module | Use Case |
-|--------|--------|----------|
-| `OpenshiftClusterAlertSender` | `monitoring/okd/` | OKD/OpenShift built-in monitoring |
-| `KubePrometheus` | `monitoring/kube_prometheus/` | Helm-deployed kube-prometheus-stack |
-| `Prometheus` | `monitoring/prometheus/` | Standalone Prometheus via Helm |
-| `RedHatClusterObservability` | `monitoring/red_hat_cluster_observability/` | RHOB operator |
-| `Grafana` | `monitoring/grafana/` | Grafana-managed alerting |
-
-### Three Levels of Monitoring
-
-#### 1. Cluster-Level Monitoring
-
-For cluster administrators. Full control over monitoring infrastructure.
-
-```rust
-// examples/okd_cluster_alerts/src/main.rs
-OpenshiftClusterAlertScore {
-    sender: OpenshiftClusterAlertSender,
-    receivers: vec![Box::new(DiscordReceiver { ... })],
-    rules: vec![Box::new(alert_rules)],
-    scrape_targets: Some(vec![Box::new(external_exporters)]),
-}
-```
-
-**Characteristics:**
-- Cluster-scoped CRDs and resources
-- Can add external scrape targets (outside cluster)
-- Manages Alertmanager configuration
-- Requires cluster-admin privileges
-
-#### 2. Tenant-Level Monitoring
-
-For teams confined to namespaces. The topology determines tenant context.
-
-```rust
-// The topology's Observability impl handles namespace scoping
-impl Observability<KubePrometheus> for K8sAnywhereTopology {
-    async fn install_rules(&self, sender: &KubePrometheus, ...) {
-        // Topology knows if it's tenant-scoped
-        let namespace = self.get_tenant_config().await
-            .map(|t| t.name)
-            .unwrap_or("default");
-        // Install rules in tenant namespace
-    }
-}
-```
-
-**Characteristics:**
-- Namespace-scoped resources
-- Cannot modify cluster-level monitoring config
-- May have restricted receiver types
-- Runtime validation of permissions (cannot be fully compile-time)
-
-#### 3. Application-Level Monitoring
-
-For developers. Zero-config, opinionated monitoring.
-
-```rust
-// modules/application/features/monitoring.rs
-pub struct Monitoring {
-    pub application: Arc<dyn Application>,
-    pub alert_receiver: Vec<Box<dyn AlertReceiver<Prometheus>>>,
-}
-
-impl<T: Topology + Observability<Prometheus> + TenantManager + ...> 
-    ApplicationFeature<T> for Monitoring 
-{
-    async fn ensure_installed(&self, topology: &T) -> Result<...> {
-        // Auto-creates ServiceMonitor
-        // Auto-installs Ntfy for notifications
-        // Handles tenant namespace automatically
-        // Wires up sensible defaults
-    }
-}
-```
-
-**Characteristics:**
-- Automatic ServiceMonitor creation
-- Opinionated notification channel (Ntfy)
-- Tenant-aware via topology
-- Minimal configuration required
-
-## Rationale
-
-### Why Generic Traits Instead of Unified Types?
-
-Each monitoring stack (OKD, KubePrometheus, RHOB) has fundamentally different CRDs:
-
-```rust
-// OKD uses AlertmanagerConfig with different structure
-AlertmanagerConfig { spec: { receivers: [...] } }
-
-// RHOB uses secret references for webhook URLs
-MonitoringStack { spec: { alertmanagerConfig: { discordConfigs: [{ apiURL: { key: "..." } }] } } }
-
-// KubePrometheus uses Alertmanager CRD with different field names
-Alertmanager { spec: { config: { receivers: [...] } } }
-```
-
-A unified type would either:
-1. Be a lowest-common-denominator (loses stack-specific features)
-2. Be a complex union type (hard to use, easy to misconfigure)
-
-Generic traits let each stack express its configuration naturally while providing a consistent interface.
-
-### Why Compile-Time Capability Bounds?
-
-```rust
-impl<T: Topology + Observability<OpenshiftClusterAlertSender>> Score<T> 
-    for OpenshiftClusterAlertScore { ... }
-```
-
-This fails at compile time if you try to use `OpenshiftClusterAlertScore` with a topology that doesn't support OKD monitoring. This prevents the "config-is-valid-but-platform-is-wrong" errors that Harmony was designed to eliminate.
-
-### Why Not a MonitoringStack Abstraction (V2 Approach)?
-
-The V2 approach proposed a unified `MonitoringStack` that hides sender selection:
-
-```rust
-// V2 approach - rejected
-MonitoringStack::new(MonitoringApiVersion::V2CRD)
-    .add_alert_channel(discord)
-```
-
-**Problems:**
-1. Hides which sender you're using, losing compile-time guarantees
-2. "Version selection" actually chooses between fundamentally different systems
-3. Would need to handle all stack-specific features through a generic interface
-
-The current approach is explicit: you choose `OpenshiftClusterAlertSender` and the compiler verifies compatibility.
-
-### Why Runtime Validation for Tenants?
-
-Tenant confinement is determined at runtime by the topology and K8s RBAC. We cannot know at compile time whether a user has cluster-admin or namespace-only access.
-
-Options considered:
-1. **Compile-time tenant markers** - Would require modeling entire RBAC hierarchy in types. Over-engineering.
-2. **Runtime validation** - Current approach. Fails with clear K8s permission errors if insufficient access.
-3. **No tenant support** - Would exclude a major use case.
-
-Runtime validation is the pragmatic choice. The failure mode is clear (K8s API error) and occurs early in execution.
-
-> Note : we will eventually have compile time validation for such things. Rust macros are powerful and we could discover the actual capabilities we're dealing with, similar to sqlx approach in query! macros.
-
-## Consequences
-
-### Pros
-
-1. **Type Safety**: Invalid configurations are caught at compile time
-2. **Extensibility**: Adding a new monitoring stack requires implementing traits, not modifying core code
-3. **Clear Separation**: Cluster/Tenant/Application levels have distinct entry points
-4. **Reusable Rules**: Pre-built alert rules as functions (`high_pvc_fill_rate_over_two_days()`)
-5. **CRD Accuracy**: Type definitions match actual Kubernetes CRDs exactly
-
-### Cons
-
-1. **Implementation Explosion**: `DiscordReceiver` implements `AlertReceiver<S>` for each sender type (3+ implementations)
-2. **Learning Curve**: Understanding the trait hierarchy takes time
-3. **clone_box Boilerplate**: Required for trait object cloning (3 lines per impl)
-
-### Mitigations
-
-- Implementation explosion is contained: each receiver type has O(senders) implementations, but receivers are rare compared to rules
-- Learning curve is documented with examples at each level
-- clone_box boilerplate is minimal and copy-paste
-
-## Alternatives Considered
-
-### Unified MonitoringStack Type
-
-See "Why Not a MonitoringStack Abstraction" above. Rejected for losing compile-time safety.
-
-### Helm-Only Approach
-
-Use `HelmScore` directly for each monitoring deployment. Rejected because:
-- No type safety for alert rules
-- Cannot compose with application features
-- No tenant awareness
-
-### Separate Modules Per Use Case
-
-Have `cluster_monitoring/`, `tenant_monitoring/`, `app_monitoring/` as separate modules. Rejected because:
-- Massive code duplication
-- No shared abstraction for receivers/rules
-- Adding a feature requires three implementations
-
-## Implementation Notes
-
-### Module Structure
-
-```
-modules/monitoring/
-├── mod.rs                     # Public exports
-├── alert_channel/             # Receivers (Discord, Webhook)
-├── alert_rule/                # Rules and pre-built alerts
-│   ├── prometheus_alert_rule.rs
-│   └── alerts/                # Library of pre-built rules
-│       ├── k8s/               # K8s-specific (pvc, pod, memory)
-│       └── infra/             # Infrastructure (opnsense, dell)
-├── okd/                       # OpenshiftClusterAlertSender
-├── kube_prometheus/           # KubePrometheus
-├── prometheus/                # Prometheus
-├── red_hat_cluster_observability/  # RHOB
-├── grafana/                   # Grafana
-├── application_monitoring/    # Application-level scores
-└── scrape_target/             # External scrape targets
-```
-
-### Adding a New Alert Sender
-
-1. Create sender type: `pub struct MySender; impl AlertSender for MySender { ... }`
-2. Implement `Observability<MySender>` for topologies that support it
-3. Create CRD types in `crd/` subdirectory
-4. Implement `AlertReceiver<MySender>` for existing receivers
-5. Implement `AlertRule<MySender>` for `AlertManagerRuleGroup`
-
-### Adding a New Alert Rule
-
-```rust
-pub fn my_custom_alert() -> PrometheusAlertRule {
-    PrometheusAlertRule::new("MyAlert", "up == 0")
-        .for_duration("5m")
-        .label("severity", "critical")
-        .annotation("summary", "Service is down")
-}
-```
-
-No trait implementation needed - `AlertManagerRuleGroup` already handles conversion.
-
-## Related ADRs
-
-- [ADR-013](013-monitoring-notifications.md): Notification channel selection (ntfy)
-- [ADR-011](011-multi-tenant-cluster.md): Multi-tenant cluster architecture

adr/020-monitoring-alerting-architecture/monitoring_v2/Cargo.toml

@@ -1,21 +0,0 @@
-[package]
-name = "example-monitoring-v2"
-edition = "2024"
-version.workspace = true
-readme.workspace = true
-license.workspace = true
-
-[dependencies]
-harmony = { path = "../../harmony" }
-harmony_cli = { path = "../../harmony_cli" }
-harmony-k8s = { path = "../../harmony-k8s" }
-harmony_types = { path = "../../harmony_types" }
-kube = { workspace = true }
-schemars = "0.8"
-serde = { workspace = true, features = ["derive"] }
-serde_json = { workspace = true }
-serde_yaml = { workspace = true }
-url = { workspace = true }
-log = { workspace = true }
-async-trait = { workspace = true }
-k8s-openapi = { workspace = true }

adr/020-monitoring-alerting-architecture/monitoring_v2/README.md

@@ -1,91 +0,0 @@
-# Monitoring v2 - Improved Architecture
-
-This example demonstrates the improved monitoring architecture that addresses the "WTF/minute" issues in the original design.
-
-## Key Improvements
-
-### 1. **Single AlertChannel Trait with Generic Sender**
-
-The original design required 9-12 implementations for each alert channel (Discord, Webhook, etc.) - one for each sender type. The new design uses a single trait with generic sender parameterization:
-
-pub trait AlertChannel<Sender: AlertSender> {
-    async fn install_config(&self, sender: &Sender) -> Result<Outcome, InterpretError>;
-    fn name(&self) -> String;
-    fn as_any(&self) -> &dyn std::any::Any;
-}
-
-**Benefits:**
-- One Discord implementation works with all sender types
-- Type safety at compile time
-- No runtime dispatch overhead
-
-### 2. **MonitoringStack Abstraction**
-
-Instead of manually selecting CRDPrometheus vs KubePrometheus vs RHOBObservability, you now have a unified MonitoringStack that handles versioning:
-
-let monitoring_stack = MonitoringStack::new(MonitoringApiVersion::V2CRD)
-    .set_namespace("monitoring")
-    .add_alert_channel(discord_receiver)
-    .set_scrape_targets(vec![...]);
-
-**Benefits:**
-- Single source of truth for monitoring configuration
-- Easy to switch between monitoring versions
-- Automatic version-specific configuration
-
-### 3. **TenantMonitoringScore - True Composition**
-
-The original monitoring_with_tenant example just put tenant and monitoring as separate items in a vec. The new design truly composes them:
-
-let tenant_score = TenantMonitoringScore::new("test-tenant", monitoring_stack);
-
-This creates a single score that:
-- Has tenant context
-- Has monitoring configuration
-- Automatically installs monitoring scoped to tenant namespace
-
-**Benefits:**
-- No more "two separate things" confusion
-- Automatic tenant namespace scoping
-- Clear ownership: tenant owns its monitoring
-
-### 4. **Versioned Monitoring APIs**
-
-Clear versioning makes it obvious which monitoring stack you're using:
-
-pub enum MonitoringApiVersion {
-    V1Helm,    // Old Helm charts
-    V2CRD,     // Current CRDs
-    V3RHOB,    // RHOB (future)
-}
-
-**Benefits:**
-- No guessing which API version you're using
-- Easy to migrate between versions
-- Backward compatibility path
-
-## Comparison
-
-### Original Design (monitoring_with_tenant)
-- Manual selection of each component
-- Manual installation of both components
-- Need to remember to pass both to harmony_cli::run
-- Monitoring not scoped to tenant automatically
-
-### New Design (monitoring_v2)
-- Single composed score
-- One score does it all
-
-## Usage
-
-cd examples/monitoring_v2
-cargo run
-
-## Migration Path
-
-To migrate from the old design to the new:
-
-1. Replace individual alert channel implementations with AlertChannel<Sender>
-2. Use MonitoringStack instead of manual *Prometheus selection
-3. Use TenantMonitoringScore instead of separate TenantScore + monitoring scores
-4. Select monitoring version via MonitoringApiVersion

adr/020-monitoring-alerting-architecture/monitoring_v2/src/lib.rs

@@ -1,343 +0,0 @@
-use std::collections::HashMap;
-use std::sync::{Arc, Mutex};
-
-
-use log::debug;
-use serde::{Deserialize, Serialize};
-use serde_yaml::{Mapping, Value};
-
-use harmony::data::Version;
-use harmony::interpret::{Interpret, InterpretError, InterpretName, InterpretStatus, Outcome};
-use harmony::inventory::Inventory;
-use harmony::score::Score;
-use harmony::topology::{Topology, tenant::TenantManager};
-
-use harmony_k8s::K8sClient;
-use harmony_types::k8s_name::K8sName;
-use harmony_types::net::Url;
-
-pub trait AlertSender: Send + Sync + std::fmt::Debug {
-    fn name(&self) -> String;
-    fn namespace(&self) -> String;
-}
-
-#[derive(Debug)]
-pub struct CRDPrometheus {
-    pub namespace: String,
-    pub client: Arc<K8sClient>,
-}
-
-impl AlertSender for CRDPrometheus {
-    fn name(&self) -> String {
-        "CRDPrometheus".to_string()
-    }
-
-    fn namespace(&self) -> String {
-        self.namespace.clone()
-    }
-}
-
-#[derive(Debug)]
-pub struct RHOBObservability {
-    pub namespace: String,
-    pub client: Arc<K8sClient>,
-}
-
-impl AlertSender for RHOBObservability {
-    fn name(&self) -> String {
-        "RHOBObservability".to_string()
-    }
-
-    fn namespace(&self) -> String {
-        self.namespace.clone()
-    }
-}
-
-#[derive(Debug)]
-pub struct KubePrometheus {
-    pub config: Arc<Mutex<KubePrometheusConfig>>,
-}
-
-impl Default for KubePrometheus {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl KubePrometheus {
-    pub fn new() -> Self {
-        Self {
-            config: Arc::new(Mutex::new(KubePrometheusConfig::new())),
-        }
-    }
-}
-
-impl AlertSender for KubePrometheus {
-    fn name(&self) -> String {
-        "KubePrometheus".to_string()
-    }
-
-    fn namespace(&self) -> String {
-        self.config.lock().unwrap().namespace.clone().unwrap_or_else(|| "monitoring".to_string())
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct KubePrometheusConfig {
-    pub namespace: Option<String>,
-    #[serde(skip)]
-    pub alert_receiver_configs: Vec<AlertManagerChannelConfig>,
-}
-
-impl KubePrometheusConfig {
-    pub fn new() -> Self {
-        Self {
-            namespace: None,
-            alert_receiver_configs: Vec::new(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct AlertManagerChannelConfig {
-    pub channel_receiver: serde_yaml::Value,
-    pub channel_route: serde_yaml::Value,
-}
-
-impl Default for AlertManagerChannelConfig {
-    fn default() -> Self {
-        Self {
-            channel_receiver: serde_yaml::Value::Mapping(Default::default()),
-            channel_route: serde_yaml::Value::Mapping(Default::default()),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ScrapeTargetConfig {
-    pub service_name: String,
-    pub port: String,
-    pub path: String,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub enum MonitoringApiVersion {
-    V1Helm,
-    V2CRD,
-    V3RHOB,
-}
-
-#[derive(Debug, Clone)]
-pub struct MonitoringStack {
-    pub version: MonitoringApiVersion,
-    pub namespace: String,
-    pub alert_channels: Vec<Arc<dyn AlertSender>>,
-    pub scrape_targets: Vec<ScrapeTargetConfig>,
-}
-
-impl MonitoringStack {
-    pub fn new(version: MonitoringApiVersion) -> Self {
-        Self {
-            version,
-            namespace: "monitoring".to_string(),
-            alert_channels: Vec::new(),
-            scrape_targets: Vec::new(),
-        }
-    }
-
-    pub fn set_namespace(mut self, namespace: &str) -> Self {
-        self.namespace = namespace.to_string();
-        self
-    }
-
-    pub fn add_alert_channel(mut self, channel: impl AlertSender + 'static) -> Self {
-        self.alert_channels.push(Arc::new(channel));
-        self
-    }
-
-    pub fn set_scrape_targets(mut self, targets: Vec<(&str, &str, String)>) -> Self {
-        self.scrape_targets = targets
-            .into_iter()
-            .map(|(name, port, path)| ScrapeTargetConfig {
-                service_name: name.to_string(),
-                port: port.to_string(),
-                path,
-            })
-            .collect();
-        self
-    }
-}
-
-pub trait AlertChannel<Sender: AlertSender> {
-    fn install_config(&self, sender: &Sender);
-    fn name(&self) -> String;
-}
-
-#[derive(Debug, Clone)]
-pub struct DiscordWebhook {
-    pub name: K8sName,
-    pub url: Url,
-    pub selectors: Vec<HashMap<String, String>>,
-}
-
-impl DiscordWebhook {
-    fn get_config(&self) -> AlertManagerChannelConfig {
-        let mut route = Mapping::new();
-        route.insert(
-            Value::String("receiver".to_string()),
-            Value::String(self.name.to_string()),
-        );
-        route.insert(
-            Value::String("matchers".to_string()),
-            Value::Sequence(vec![Value::String("alertname!=Watchdog".to_string())]),
-        );
-
-        let mut receiver = Mapping::new();
-        receiver.insert(
-            Value::String("name".to_string()),
-            Value::String(self.name.to_string()),
-        );
-
-        let mut discord_config = Mapping::new();
-        discord_config.insert(
-            Value::String("webhook_url".to_string()),
-            Value::String(self.url.to_string()),
-        );
-
-        receiver.insert(
-            Value::String("discord_configs".to_string()),
-            Value::Sequence(vec![Value::Mapping(discord_config)]),
-        );
-
-        AlertManagerChannelConfig {
-            channel_receiver: Value::Mapping(receiver),
-            channel_route: Value::Mapping(route),
-        }
-    }
-}
-
-impl AlertChannel<CRDPrometheus> for DiscordWebhook {
-    fn install_config(&self, sender: &CRDPrometheus) {
-        debug!("Installing Discord webhook for CRDPrometheus in namespace: {}", sender.namespace());
-        debug!("Config: {:?}", self.get_config());
-        debug!("Installed!");
-    }
-
-    fn name(&self) -> String {
-        "discord-webhook".to_string()
-    }
-}
-
-impl AlertChannel<RHOBObservability> for DiscordWebhook {
-    fn install_config(&self, sender: &RHOBObservability) {
-        debug!("Installing Discord webhook for RHOBObservability in namespace: {}", sender.namespace());
-        debug!("Config: {:?}", self.get_config());
-        debug!("Installed!");
-    }
-
-    fn name(&self) -> String {
-        "webhook-receiver".to_string()
-    }
-}
-
-impl AlertChannel<KubePrometheus> for DiscordWebhook {
-    fn install_config(&self, sender: &KubePrometheus) {
-        debug!("Installing Discord webhook for KubePrometheus in namespace: {}", sender.namespace());
-        let config = sender.config.lock().unwrap();
-        let ns = config.namespace.clone().unwrap_or_else(|| "monitoring".to_string());
-        debug!("Namespace: {}", ns);
-        let mut config = sender.config.lock().unwrap();
-        config.alert_receiver_configs.push(self.get_config());
-        debug!("Installed!");
-    }
-
-    fn name(&self) -> String {
-        "discord-webhook".to_string()
-    }
-}
-
-fn default_monitoring_stack() -> MonitoringStack {
-    MonitoringStack::new(MonitoringApiVersion::V2CRD)
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct TenantMonitoringScore {
-    pub tenant_id: harmony_types::id::Id,
-    pub tenant_name: String,
-    #[serde(skip)]
-    #[serde(default = "default_monitoring_stack")]
-    pub monitoring_stack: MonitoringStack,
-}
-
-impl TenantMonitoringScore {
-    pub fn new(tenant_name: &str, monitoring_stack: MonitoringStack) -> Self {
-        Self {
-            tenant_id: harmony_types::id::Id::default(),
-            tenant_name: tenant_name.to_string(),
-            monitoring_stack,
-        }
-    }
-}
-
-impl<T: Topology + TenantManager> Score<T> for TenantMonitoringScore {
-    fn create_interpret(&self) -> Box<dyn Interpret<T>> {
-        Box::new(TenantMonitoringInterpret {
-            score: self.clone(),
-        })
-    }
-
-    fn name(&self) -> String {
-        format!("{} monitoring [TenantMonitoringScore]", self.tenant_name)
-    }
-}
-
-#[derive(Debug)]
-pub struct TenantMonitoringInterpret {
-    pub score: TenantMonitoringScore,
-}
-
-#[async_trait::async_trait]
-impl<T: Topology + TenantManager> Interpret<T> for TenantMonitoringInterpret {
-    async fn execute(
-        &self,
-        _inventory: &Inventory,
-        topology: &T,
-    ) -> Result<Outcome, InterpretError> {
-        let tenant_config = topology.get_tenant_config().await.unwrap();
-        let tenant_ns = tenant_config.name.clone();
-
-        match self.score.monitoring_stack.version {
-            MonitoringApiVersion::V1Helm => {
-                debug!("Installing Helm monitoring for tenant {}", tenant_ns);
-            }
-            MonitoringApiVersion::V2CRD => {
-                debug!("Installing CRD monitoring for tenant {}", tenant_ns);
-            }
-            MonitoringApiVersion::V3RHOB => {
-                debug!("Installing RHOB monitoring for tenant {}", tenant_ns);
-            }
-        }
-
-        Ok(Outcome::success(format!(
-            "Installed monitoring stack for tenant {} with version {:?}",
-            self.score.tenant_name,
-            self.score.monitoring_stack.version
-        )))
-    }
-
-    fn get_name(&self) -> InterpretName {
-        InterpretName::Custom("TenantMonitoringInterpret")
-    }
-
-    fn get_version(&self) -> Version {
-        Version::from("1.0.0").unwrap()
-    }
-
-    fn get_status(&self) -> InterpretStatus {
-        InterpretStatus::SUCCESS
-    }
-
-    fn get_children(&self) -> Vec<harmony_types::id::Id> {
-        Vec::new()
-    }
-}

book.toml

@@ -0,0 +1,9 @@
+[book]
+title = "Harmony"
+description = "Infrastructure orchestration that treats your platform like first-class code"
+src = "docs"
+build-dir = "book"
+authors = ["NationTech"]
+
+[output.html]
+mathjax-support = false

build/book.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+cd "$(dirname "$0")/.."
+
+cargo install mdbook --locked
+mdbook build
+
+test -f book/index.html || (echo "ERROR: book/index.html not found" && exit 1)
+test -f book/concepts.html || (echo "ERROR: book/concepts.html not found" && exit 1)
+test -f book/guides/getting-started.html || (echo "ERROR: book/guides/getting-started.html not found" && exit 1)

build/check.sh

@@ -1,6 +1,8 @@
 #!/bin/sh
 set -e
 
+cd "$(dirname "$0")/.."
+
 rustc --version
 cargo check --all-targets --all-features --keep-going
 cargo fmt --check

build/ci.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -e
+
+cd "$(dirname "$0")/.."
+
+BRANCH="${1:-main}"
+
+echo "=== Running CI for branch: $BRANCH ==="
+
+echo "--- Checking code ---"
+./build/check.sh
+
+echo "--- Building book ---"
+./build/book.sh
+
+echo "=== CI passed ==="

docs/README.md

@@ -13,8 +13,8 @@ If you're new to Harmony, start here:
 
 See how to use Harmony to solve real-world problems.
 
+- [**PostgreSQL on Local K3D**](./use-cases/postgresql-on-local-k3d.md): Deploy a production-grade PostgreSQL cluster on a local K3D cluster. The fastest way to get started.
 - [**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
 
@@ -31,16 +31,7 @@ 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`.
-- [**Coding Guide**](./coding-guide.md): Conventions and best practices for writing Harmony code.
 
-## 5. Module Documentation
+## 5. Architecture Decision Records
 
-Deep dives into specific Harmony modules and features.
-
-- [**Monitoring and Alerting**](./monitoring.md): Comprehensive guide to cluster, tenant, and application-level monitoring with support for OKD, KubePrometheus, RHOB, and more.
-
-## 6. Architecture Decision Records
-
-Important architectural decisions are documented in the `adr/` directory:
-
-- [Full ADR Index](../adr/)
+Harmony's design is documented through Architecture Decision Records (ADRs). See the [ADR Overview](./adr/README.md) for a complete index of all decisions.

docs/SUMMARY.md

@@ -0,0 +1,53 @@
+# Summary
+
+[Harmony Documentation](./README.md)
+
+- [Core Concepts](./concepts.md)
+- [Getting Started Guide](./guides/getting-started.md)
+
+## Use Cases
+
+- [PostgreSQL on Local K3D](./use-cases/postgresql-on-local-k3d.md)
+- [OKD on Bare Metal](./use-cases/okd-on-bare-metal.md)
+
+## Component Catalogs
+
+- [Scores Catalog](./catalogs/scores.md)
+- [Topologies Catalog](./catalogs/topologies.md)
+- [Capabilities Catalog](./catalogs/capabilities.md)
+
+## Developer Guides
+
+- [Developer Guide](./guides/developer-guide.md)
+- [Writing a Score](./guides/writing-a-score.md)
+- [Writing a Topology](./guides/writing-a-topology.md)
+- [Adding Capabilities](./guides/adding-capabilities.md)
+
+## Configuration
+
+- [Configuration](./concepts/configuration.md)
+
+## Architecture Decision Records
+
+- [ADR Overview](./adr/README.md)
+   - [000 · ADR Template](./adr/000-ADR-Template.md)
+   - [001 · Why Rust](./adr/001-rust.md)
+   - [002 · Hexagonal Architecture](./adr/002-hexagonal-architecture.md)
+   - [003 · Infrastructure Abstractions](./adr/003-infrastructure-abstractions.md)
+   - [004 · iPXE](./adr/004-ipxe.md)
+   - [005 · Interactive Project](./adr/005-interactive-project.md)
+   - [006 · Secret Management](./adr/006-secret-management.md)
+   - [007 · Default Runtime](./adr/007-default-runtime.md)
+   - [008 · Score Display Formatting](./adr/008-score-display-formatting.md)
+   - [009 · Helm and Kustomize Handling](./adr/009-helm-and-kustomize-handling.md)
+   - [010 · Monitoring and Alerting](./adr/010-monitoring-and-alerting.md)
+   - [011 · Multi-Tenant Cluster](./adr/011-multi-tenant-cluster.md)
+   - [012 · Project Delivery Automation](./adr/012-project-delivery-automation.md)
+   - [013 · Monitoring Notifications](./adr/013-monitoring-notifications.md)
+   - [015 · Higher Order Topologies](./adr/015-higher-order-topologies.md)
+   - [016 · Harmony Agent and Global Mesh](./adr/016-Harmony-Agent-And-Global-Mesh-For-Decentralized-Workload-Management.md)
+   - [017-1 · NATS Clusters Interconnection](./adr/017-1-Nats-Clusters-Interconnection-Topology.md)
+   - [018 · Template Hydration for Workload Deployment](./adr/018-Template-Hydration-For-Workload-Deployment.md)
+   - [019 · Network Bond Setup](./adr/019-Network-bond-setup.md)
+   - [020 · Interactive Configuration Crate](./adr/020-interactive-configuration-crate.md)
+   - [020-1 · Zitadel + OpenBao Secure Config Store](./adr/020-1-zitadel-openbao-secure-config-store.md)

docs/adr/006-secret-management.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Proposed
+Rejected : See ADR 020 ./020-interactive-configuration-crate.md
 
 ### TODO [#3](https://git.nationtech.io/NationTech/harmony/issues/3):
 

docs/adr/020-1-zitadel-openbao-secure-config-store.md

@@ -0,0 +1,233 @@
+# ADR 020-1: Zitadel OIDC and OpenBao Integration for the Config Store
+
+Author: Jean-Gabriel Gill-Couture
+
+Date: 2026-03-18
+
+## Status
+
+Proposed
+
+## Context
+
+ADR 020 defines a unified `harmony_config` crate with a `ConfigStore` trait. The default team-oriented backend is OpenBao, which provides encrypted storage, versioned KV, audit logging, and fine-grained access control.
+
+OpenBao requires authentication. The question is how developers authenticate without introducing new credentials to manage.
+
+The goals are:
+
+- **Zero new credentials.** Developers log in with their existing corporate identity (Google Workspace, GitHub, or Microsoft Entra ID / Azure AD).
+- **Headless compatibility.** The flow must work over SSH, inside containers, and in CI — environments with no browser or localhost listener.
+- **Minimal friction.** After a one-time login, authentication should be invisible for weeks of active use.
+- **Centralized offboarding.** Revoking a user in the identity provider must immediately revoke their access to the config store.
+
+## Decision
+
+Developers authenticate to OpenBao through a two-step process: first, they obtain an OIDC token from Zitadel (`sso.nationtech.io`) using the OAuth 2.0 Device Authorization Grant (RFC 8628); then, they exchange that token for a short-lived OpenBao client token via OpenBao's JWT auth method.
+
+### The authentication flow
+
+#### Step 1: Trigger
+
+The `ConfigManager` attempts to resolve a value via the `StoreSource`. The `StoreSource` checks for a cached OpenBao token in `~/.local/share/harmony/session.json`. If the token is missing or expired, authentication begins.
+
+#### Step 2: Device Authorization Request
+
+Harmony sends a `POST` to Zitadel's device authorization endpoint:
+
+```
+POST https://sso.nationtech.io/oauth/v2/device_authorization
+Content-Type: application/x-www-form-urlencoded
+
+client_id=<harmony_client_id>&scope=openid email profile offline_access
+```
+
+Zitadel responds with:
+
+```json
+{
+  "device_code": "dOcbPeysDhT26ZatRh9n7Q",
+  "user_code": "GQWC-FWFK",
+  "verification_uri": "https://sso.nationtech.io/device",
+  "verification_uri_complete": "https://sso.nationtech.io/device?user_code=GQWC-FWFK",
+  "expires_in": 300,
+  "interval": 5
+}
+```
+
+#### Step 3: User prompt
+
+Harmony prints the code and URL to the terminal:
+
+```
+[Harmony] To authenticate, open your browser to:
+          https://sso.nationtech.io/device
+          and enter code: GQWC-FWFK
+
+          Or visit: https://sso.nationtech.io/device?user_code=GQWC-FWFK
+```
+
+If a desktop environment is detected, Harmony also calls `open` / `xdg-open` to launch the browser automatically. The `verification_uri_complete` URL pre-fills the code, so the user only needs to click "Confirm" after logging in.
+
+There is no localhost HTTP listener. The CLI does not need to bind a port or receive a callback. This is what makes the device flow work over SSH, in containers, and through corporate firewalls — unlike the `oc login` approach which spins up a temporary web server to catch a redirect.
+
+#### Step 4: User login
+
+The developer logs in through Zitadel's web UI using one of the configured identity providers:
+
+- **Google Workspace** — for teams using Google as their corporate identity.
+- **GitHub** — for open-source or GitHub-centric teams.
+- **Microsoft Entra ID (Azure AD)** — for enterprise clients, particularly common in Quebec and the broader Canadian public sector.
+
+Zitadel federates the login to the chosen provider. The developer authenticates with their existing corporate credentials. No new password is created.
+
+#### Step 5: Polling
+
+While the user is authenticating in the browser, Harmony polls Zitadel's token endpoint at the interval specified in the device authorization response (typically 5 seconds):
+
+```
+POST https://sso.nationtech.io/oauth/v2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:device_code
+&device_code=dOcbPeysDhT26ZatRh9n7Q
+&client_id=<harmony_client_id>
+```
+
+Before the user completes login, Zitadel responds with `authorization_pending`. Once the user consents, Zitadel returns:
+
+```json
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "...",
+  "id_token": "eyJhbGciOiJSUzI1NiIs..."
+}
+```
+
+The `scope=offline_access` in the initial request is what causes Zitadel to issue a `refresh_token`.
+
+#### Step 6: OpenBao JWT exchange
+
+Harmony sends the `id_token` (a JWT signed by Zitadel) to OpenBao's JWT auth method:
+
+```
+POST https://secrets.nationtech.io/v1/auth/jwt/login
+Content-Type: application/json
+
+{
+  "role": "harmony-developer",
+  "jwt": "eyJhbGciOiJSUzI1NiIs..."
+}
+```
+
+OpenBao validates the JWT:
+
+1. It fetches Zitadel's public keys from `https://sso.nationtech.io/oauth/v2/keys` (the JWKS endpoint).
+2. It verifies the JWT signature.
+3. It reads the claims (`email`, `groups`, and any custom claims mapped from the upstream identity provider, such as Azure AD tenant or Google Workspace org).
+4. It evaluates the claims against the `bound_claims` and `bound_audiences` configured on the `harmony-developer` role.
+5. If validation passes, OpenBao returns a client token:
+
+```json
+{
+  "auth": {
+    "client_token": "hvs.CAES...",
+    "policies": ["harmony-dev"],
+    "metadata": { "role": "harmony-developer" },
+    "lease_duration": 14400,
+    "renewable": true
+  }
+}
+```
+
+Harmony caches the OpenBao token, the OIDC refresh token, and the token expiry timestamps to `~/.local/share/harmony/session.json` with `0600` file permissions.
+
+### OpenBao storage structure
+
+All configuration and secret state is stored in an OpenBao Versioned KV v2 engine.
+
+Path taxonomy:
+
+```
+harmony/<organization>/<project>/<environment>/<key>
+```
+
+Examples:
+
+```
+harmony/nationtech/my-app/staging/PostgresConfig
+harmony/nationtech/my-app/production/PostgresConfig
+harmony/nationtech/my-app/local-shared/PostgresConfig
+```
+
+The `ConfigClass` (Standard vs. Secret) can influence OpenBao policy structure — for example, `Secret`-class paths could require stricter ACLs or additional audit backends — but the path taxonomy itself does not change. This is an operational concern configured in OpenBao policies, not a structural one enforced by path naming.
+
+### Token lifecycle and silent refresh
+
+The system manages three tokens with different lifetimes:
+
+| Token | TTL | Max TTL | Purpose |
+|---|---|---|---|
+| OpenBao client token | 4 hours | 24 hours | Read/write config store |
+| OIDC ID token | 1 hour | — | Exchange for OpenBao token |
+| OIDC refresh token | 90 days absolute, 30 days inactivity | — | Obtain new ID tokens silently |
+
+The refresh flow, from the developer's perspective:
+
+1. **Same session (< 4 hours since last use).** The cached OpenBao token is still valid. No network call to Zitadel. Fastest path.
+2. **Next day (OpenBao token expired, refresh token valid).** Harmony uses the OIDC `refresh_token` to request a new `id_token` from Zitadel's token endpoint (`grant_type=refresh_token`). It then exchanges the new `id_token` for a fresh OpenBao token. This happens silently. The developer sees no prompt.
+3. **OpenBao token near max TTL (approaching 24 hours of cumulative renewals).** Instead of renewing, Harmony re-authenticates using the refresh token to get a completely fresh OpenBao token. Transparent to the user.
+4. **After 30 days of inactivity.** The OIDC refresh token expires. Harmony falls back to the device flow (Step 2 above) and prompts the user to re-authenticate in the browser. This is the only scenario where a returning developer sees a login prompt.
+5. **User offboarded.** An administrator revokes the user's account or group membership in Zitadel. The next time the refresh token is used, Zitadel rejects it. The device flow also fails because the user can no longer authenticate. Access is terminated without any action needed on the OpenBao side.
+
+OpenBao token renewal uses the `/auth/token/renew-self` endpoint with the `X-Vault-Token` header. Harmony renews proactively at ~75% of the TTL to avoid race conditions.
+
+### OpenBao role configuration
+
+The OpenBao JWT auth role for Harmony developers:
+
+```bash
+bao write auth/jwt/config \
+    oidc_discovery_url="https://sso.nationtech.io" \
+    bound_issuer="https://sso.nationtech.io"
+
+bao write auth/jwt/role/harmony-developer \
+    role_type="jwt" \
+    bound_audiences="<harmony_client_id>" \
+    user_claim="email" \
+    groups_claim="urn:zitadel:iam:org:project:roles" \
+    policies="harmony-dev" \
+    ttl="4h" \
+    max_ttl="24h" \
+    token_type="service"
+```
+
+The `bound_audiences` claim ties the role to the specific Harmony Zitadel application. The `groups_claim` allows mapping Zitadel project roles to OpenBao policies for per-team or per-project access control.
+
+### Self-hosted deployments
+
+For organizations running their own infrastructure, the same architecture applies. The operator deploys Zitadel and OpenBao using Harmony's existing `ZitadelScore` and `OpenbaoScore`. The only configuration needed is three environment variables (or their equivalents in the bootstrap config):
+
+- `HARMONY_SSO_URL` — the Zitadel instance URL.
+- `HARMONY_SECRETS_URL` — the OpenBao instance URL.
+- `HARMONY_SSO_CLIENT_ID` — the Zitadel application client ID.
+
+None of these are secrets. They can be committed to an infrastructure repository or distributed via any convenient channel.
+
+## Consequences
+
+### Positive
+
+- Developers authenticate with existing corporate credentials. No new passwords, no static tokens to distribute.
+- The device flow works in every environment: local terminal, SSH, containers, CI runners, corporate VPNs.
+- Silent token refresh keeps developers authenticated for weeks without any manual intervention.
+- User offboarding is a single action in Zitadel. No OpenBao token rotation or manual revocation required.
+- Azure AD / Microsoft Entra ID support addresses the enterprise and public sector market.
+
+### Negative
+
+- The OAuth state machine (device code polling, token refresh, error handling) adds implementation complexity compared to a static token approach.
+- Developers must have network access to `sso.nationtech.io` and `secrets.nationtech.io` to pull or push configuration state. True offline work falls back to the local file store, which does not sync with the team.
+- The first login per machine requires a browser interaction. Fully headless first-run scenarios (e.g., a fresh CI runner with no pre-seeded tokens) must use `EnvSource` overrides or a service account JWT.

docs/adr/020-interactive-configuration-crate.md

@@ -0,0 +1,177 @@
+# ADR 020: Unified Configuration and Secret Management
+
+Author: Jean-Gabriel Gill-Couture
+
+Date: 2026-03-18
+
+## Status
+
+Proposed
+
+## Context
+
+Harmony's orchestration logic depends on runtime data that falls into two categories:
+
+1. **Secrets** — credentials, tokens, private keys.
+2. **Operational configuration** — deployment targets, host selections, port assignments, reboot decisions, and similar contextual choices.
+
+Both categories share the same fundamental lifecycle: a value must be acquired before execution can proceed, it may come from several backends (environment variable, remote store, interactive prompt), and it must be shareable across a team without polluting the Git repository.
+
+Treating these categories as separate subsystems forces developers to choose between a "config API" and a "secret API" at every call site. The only meaningful difference between the two is how the storage backend handles the data (plaintext vs. encrypted, audited vs. unaudited) and how the CLI displays it (visible vs. masked). That difference belongs in the backend, not in the application code.
+
+Three concrete problems drive this change:
+
+- **Async terminal corruption.** `inquire` prompts assume exclusive terminal ownership. Background tokio tasks emitting log output during a prompt corrupt the terminal state. This is inherent to Harmony's concurrent orchestration model.
+- **Untestable code paths.** Any function containing an inline `inquire` call requires a real TTY to execute. Unit testing is impossible without ignoring the test entirely.
+- **No backend integration.** Inline prompts cannot be answered from a remote store, an environment variable, or a CI pipeline. Every automated deployment that passes through a prompting code path requires a human operator at a terminal.
+
+## Decision
+
+A single workspace crate, `harmony_config`, provides all configuration and secret acquisition for Harmony. It replaces both `harmony_secret` and all inline `inquire` usage.
+
+### Schema in Git, state in the store
+
+The Rust type system serves as the configuration schema. Developers declare what configuration is needed by defining structs:
+
+```rust
+#[derive(Config, Serialize, Deserialize, JsonSchema, InteractiveParse)]
+struct PostgresConfig {
+    pub host: String,
+    pub port: u16,
+    #[config(secret)]
+    pub password: String,
+}
+```
+
+These structs live in Git and evolve with the code. When a branch introduces a new field, Git tracks that schema change. The actual values live in an external store — OpenBao by default. No `.env` files, no JSON config files, no YAML in the repository.
+
+### Data classification
+
+```rust
+/// Tells the storage backend how to handle the data.
+pub enum ConfigClass {
+    /// Plaintext storage is acceptable.
+    Standard,
+    /// Must be encrypted at rest, masked in UI, subject to audit logging.
+    Secret,
+}
+```
+
+Classification is determined at the struct level. A struct with no `#[config(secret)]` fields has `ConfigClass::Standard`. A struct with one or more `#[config(secret)]` fields is elevated to `ConfigClass::Secret`. The struct is always stored as a single cohesive JSON blob; field-level splitting across backends is not a concern of the trait.
+
+The `#[config(secret)]` attribute also instructs the `PromptSource` to mask terminal input for that field during interactive prompting.
+
+### The Config trait
+
+```rust
+pub trait Config: Serialize + DeserializeOwned + JsonSchema + InteractiveParseObj + Sized {
+    /// Stable lookup key. By default, the struct name.
+    const KEY: &'static str;
+
+    /// How the backend should treat this data.
+    const CLASS: ConfigClass;
+}
+```
+
+A `#[derive(Config)]` proc macro generates the implementation. The macro inspects field attributes to determine `CLASS`.
+
+### The ConfigStore trait
+
+```rust
+#[async_trait]
+pub trait ConfigStore: Send + Sync {
+    async fn get(
+        &self,
+        class: ConfigClass,
+        namespace: &str,
+        key: &str,
+    ) -> Result<Option<serde_json::Value>, ConfigError>;
+
+    async fn set(
+        &self,
+        class: ConfigClass,
+        namespace: &str,
+        key: &str,
+        value: &serde_json::Value,
+    ) -> Result<(), ConfigError>;
+}
+```
+
+The `class` parameter is a hint. The store implementation decides what to do with it. An OpenBao store may route `Secret` data to a different path prefix or apply stricter ACLs. A future store could split fields across backends — that is an implementation concern, not a trait concern.
+
+### Resolution chain
+
+The `ConfigManager` tries sources in priority order:
+
+1. **`EnvSource`** — reads `HARMONY_CONFIG_{KEY}` as a JSON string. Override hatch for CI/CD pipelines and containerized environments.
+2. **`StoreSource`** — wraps a `ConfigStore` implementation. For teams, this is the OpenBao backend authenticated via Zitadel OIDC (see ADR 020-1).
+3. **`PromptSource`** — presents an `interactive-parse` prompt on the terminal. Acquires a process-wide async mutex before rendering to prevent log output corruption.
+
+When `PromptSource` obtains a value, the `ConfigManager` persists it back to the `StoreSource` so that subsequent runs — by the same developer or any teammate — resolve without prompting.
+
+Callers that do not include `PromptSource` in their source list never block on a TTY. Test code passes empty source lists and constructs config structs directly.
+
+### Schema versioning
+
+The Rust struct is the schema. When a developer renames a field, removes a field, or changes a type on a branch, the store may still contain data shaped for a previous version of the struct. If another team member who does not yet have that commit runs the code, `serde_json::from_value` will fail on the stale entry.
+
+In the initial implementation, the resolution chain handles this gracefully: a deserialization failure is treated as a cache miss, and the `PromptSource` fires. The prompted value overwrites the stale entry in the store.
+
+This is sufficient for small teams working on short-lived branches. It is not sufficient at scale, where silent re-prompting could mask real configuration drift.
+
+A future iteration will introduce a compile-time schema migration mechanism, similar to how `sqlx` verifies queries against a live database at compile time. The mechanism will:
+
+- Detect schema drift between the Rust struct and the stored JSON.
+- Apply named, ordered migration functions to transform stored data forward.
+- Reject ambiguous migrations at compile time rather than silently corrupting state.
+
+Until that mechanism exists, teams should treat store entries as soft caches: the struct definition is always authoritative, and the store is best-effort.
+
+## Rationale
+
+**Why merge secrets and config into one crate?** Separate crates with nearly identical trait shapes (`Secret` vs `Config`, `SecretStore` vs `ConfigStore`) force developers to make a classification decision at every call site. A unified crate with a `ConfigClass` discriminator moves that decision to the struct definition, where it belongs.
+
+**Why OpenBao as the default backend?** OpenBao is a fully open-source Vault fork under the Linux Foundation. It runs on-premises with no phone-home requirement — a hard constraint for private cloud and regulated environments. Harmony already deploys OpenBao for clients (`OpenbaoScore`), so no new infrastructure is introduced.
+
+**Why not store values in Git (e.g., encrypted YAML)?** Git-tracked config files create merge conflicts, require re-encryption on team membership changes, and leak metadata (file names, key names) even when values are encrypted. Storing state in OpenBao avoids all of these issues and provides audit logging, access control, and versioned KV out of the box.
+
+**Why keep `PromptSource`?** Removing interactive prompts entirely would break the zero-infrastructure bootstrapping path and eliminate human-confirmation safety gates for destructive operations (interface reconfiguration, node reboot). The problem was never that prompts exist — it is that they were unavoidable and untestable. Making `PromptSource` an explicit, opt-in entry in the source list restores control.
+
+## Consequences
+
+### Positive
+
+- A single API surface for all runtime data acquisition.
+- All currently-ignored tests become runnable without TTY access.
+- Async terminal corruption is eliminated by the process-wide prompt mutex.
+- The bootstrapping path requires no infrastructure for a first run; `PromptSource` alone is sufficient.
+- The team path (OpenBao + Zitadel) reuses infrastructure Harmony already deploys.
+- User offboarding is a single Zitadel action.
+
+### Negative
+
+- Migrating all inline `inquire` and `harmony_secret` call sites is a significant refactoring effort.
+- Until the schema migration mechanism is built, store entries for renamed or removed fields become stale and must be re-prompted.
+- The Zitadel device flow introduces a browser step on first login per machine.
+
+## Implementation Plan
+
+### Phase 1: Trait design and crate restructure
+
+Refactor `harmony_config` to define the final `Config`, `ConfigClass`, and `ConfigStore` traits. Update the derive macro to support `#[config(secret)]` and generate the correct `CLASS` constant. Implement `EnvSource` and `PromptSource` against the new traits. Write comprehensive unit tests using mock stores.
+
+### Phase 2: Absorb `harmony_secret`
+
+Migrate the `OpenbaoSecretStore`, `InfisicalSecretStore`, and `LocalFileSecretStore` implementations from `harmony_secret` into `harmony_config` as `ConfigStore` backends. Update all call sites that use `SecretManager::get`, `SecretManager::get_or_prompt`, or `SecretManager::set` to use `harmony_config` equivalents.
+
+### Phase 3: Migrate inline prompts
+
+Replace all inline `inquire` call sites in the `harmony` crate (`infra/brocade.rs`, `infra/network_manager.rs`, `modules/okd/host_network.rs`, and others) with `harmony_config` structs and `get_or_prompt` calls. Un-ignore the affected tests.
+
+### Phase 4: Zitadel and OpenBao integration
+
+Implement the authentication flow described in ADR 020-1. Wire `StoreSource` to use Zitadel OIDC tokens for OpenBao access. Implement token caching and silent refresh.
+
+### Phase 5: Remove `harmony_secret`
+
+Delete the `harmony_secret` and `harmony_secret_derive` crates from the workspace. All functionality now lives in `harmony_config`.

docs/adr/README.md

@@ -0,0 +1,63 @@
+# Architecture Decision Records
+
+An Architecture Decision Record (ADR) documents a significant architectural decision made during the development of Harmony — along with its context, rationale, and consequences.
+
+## Why We Use ADRs
+
+As a platform engineering framework used by a team, Harmony accumulates technical decisions over time. ADRs help us:
+
+- **Track rationale** — understand _why_ a decision was made, not just _what_ was decided
+- ** onboard new contributors** — the "why" is preserved even when team membership changes
+- **Avoid repeating past mistakes** — previous decisions and their context are searchable
+- **Manage technical debt** — ADRs make it easier to revisit and revise past choices
+
+An ADR captures a decision at a point in time. It is not a specification — it is a record of reasoning.
+
+## ADR Format
+
+Every ADR follows this structure:
+
+| Section | Purpose |
+|---------|---------|
+| **Status** | Proposed / Pending / Accepted / Implemented / Deprecated |
+| **Context** | The problem or background — the "why" behind this decision |
+| **Decision** | The chosen solution or direction |
+| **Rationale** | Reasoning behind the decision |
+| **Consequences** | Both positive and negative outcomes |
+| **Alternatives considered** | Other options that were evaluated |
+| **Additional Notes** | Supplementary context, links, or open questions |
+
+## ADR Index
+
+| Number | Title | Status |
+|--------|-------|--------|
+| [000](./000-ADR-Template.md) | ADR Template | Reference |
+| [001](./001-rust.md) | Why Rust | Accepted |
+| [002](./002-hexagonal-architecture.md) | Hexagonal Architecture | Accepted |
+| [003](./003-infrastructure-abstractions.md) | Infrastructure Abstractions | Accepted |
+| [004](./004-ipxe.md) | iPXE | Accepted |
+| [005](./005-interactive-project.md) | Interactive Project | Proposed |
+| [006](./006-secret-management.md) | Secret Management | Accepted |
+| [007](./007-default-runtime.md) | Default Runtime | Accepted |
+| [008](./008-score-display-formatting.md) | Score Display Formatting | Proposed |
+| [009](./009-helm-and-kustomize-handling.md) | Helm and Kustomize Handling | Accepted |
+| [010](./010-monitoring-and-alerting.md) | Monitoring and Alerting | Accepted |
+| [011](./011-multi-tenant-cluster.md) | Multi-Tenant Cluster | Accepted |
+| [012](./012-project-delivery-automation.md) | Project Delivery Automation | Proposed |
+| [013](./013-monitoring-notifications.md) | Monitoring Notifications | Accepted |
+| [015](./015-higher-order-topologies.md) | Higher Order Topologies | Proposed |
+| [016](./016-Harmony-Agent-And-Global-Mesh-For-Decentralized-Workload-Management.md) | Harmony Agent and Global Mesh | Proposed |
+| [017-1](./017-1-Nats-Clusters-Interconnection-Topology.md) | NATS Clusters Interconnection Topology | Proposed |
+| [018](./018-Template-Hydration-For-Workload-Deployment.md) | Template Hydration for Workload Deployment | Proposed |
+| [019](./019-Network-bond-setup.md) | Network Bond Setup | Proposed |
+| [020-1](./020-1-zitadel-openbao-secure-config-store.md) | Zitadel + OpenBao Secure Config Store | Accepted |
+| [020](./020-interactive-configuration-crate.md) | Interactive Configuration Crate | Proposed |
+
+## Contributing
+
+When making a significant technical change:
+
+1. **Check existing ADRs** — the decision may already be documented
+2. **Create a new ADR** using the [template](./000-ADR-Template.md) if the change warrants architectural discussion
+3. **Set status to Proposed** and open it for team review
+4. Once accepted and implemented, update the status accordingly

docs/catalogs/scores.md

@@ -84,7 +84,7 @@ Network services that run inside the cluster or as part of the topology.
 - **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.
+- **HighAvailabilityHostNetworkScore**: Configures network bonds on a host and the corresponding port-channels on the switch stack for high-availability.
 
 ## Tenant Management
 

docs/concepts.md

@@ -28,6 +28,11 @@ Harmony's design is based on a few key concepts. Understanding them is the key t
 - **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.
 
+### 6. Configuration & Secrets
+
+- **What it is:** Configuration represents the runtime data required to deploy your `Scores`. This includes both non-sensitive state (like cluster hostnames, deployment profiles) and sensitive secrets (like API keys, database passwords).
+- **How it works:** See the [Configuration Concept Guide](./concepts/configuration.md) to understand Harmony's unified approach to managing schema in Git and state in OpenBao.
+
 ---
 
 ### How They Work Together (The Compile-Time Check)

docs/concepts/configuration.md

@@ -0,0 +1,107 @@
+# Configuration and Secrets
+
+Harmony treats configuration and secrets as a single concern. Developers use one crate, `harmony_config`, to declare, store, and retrieve all runtime data — whether it is a public hostname or a database password.
+
+## The mental model: schema in Git, state in the store
+
+### Schema
+
+In Harmony, the Rust code is the configuration schema. You declare what your module needs by defining a struct:
+
+```rust
+#[derive(Config, Serialize, Deserialize, JsonSchema, InteractiveParse)]
+struct PostgresConfig {
+    pub host: String,
+    pub port: u16,
+    #[config(secret)]
+    pub password: String,
+}
+```
+
+This struct is tracked in Git. When a branch adds a new field, Git tracks that the branch requires a new value. When a branch removes a field, the old value in the store becomes irrelevant. The struct is always authoritative.
+
+### State
+
+The actual values live in a config store — by default, OpenBao. No `.env` files, no JSON, no YAML in the repository.
+
+When you run your code, Harmony reads the struct (schema) and resolves values from the store (state):
+
+- If the store has the value, it is injected seamlessly.
+- If the store does not have it, Harmony prompts you in the terminal. Your answer is pushed back to the store automatically.
+- When a teammate runs the same code, they are not prompted — you already provided the value.
+
+### How branch switching works
+
+Because the schema is just Rust code tracked in Git, branch switching works naturally:
+
+1. You check out `feat/redis`. The code now requires `RedisConfig`.
+2. You run `cargo run`. Harmony detects that `RedisConfig` has no value in the store. It prompts you.
+3. You provide the values. Harmony pushes them to OpenBao.
+4. Your teammate checks out `feat/redis` and runs `cargo run`. No prompt — the values are already in the store.
+5. You switch back to `main`. `RedisConfig` does not exist in that branch's code. The store entry is ignored.
+
+## Secrets vs. standard configuration
+
+From your application code, there is no difference. You always call `harmony_config::get_or_prompt::<T>()`.
+
+The difference is in the struct definition:
+
+```rust
+// Standard config — stored in plaintext, displayed during prompting.
+#[derive(Config)]
+struct ClusterConfig {
+    pub api_url: String,
+    pub namespace: String,
+}
+
+// Contains a secret field — the entire struct is stored encrypted,
+// and the password field is masked during terminal prompting.
+#[derive(Config)]
+struct DatabaseConfig {
+    pub host: String,
+    #[config(secret)]
+    pub password: String,
+}
+```
+
+If a struct contains any `#[config(secret)]` field, Harmony elevates the entire struct to `ConfigClass::Secret`. The storage backend decides what that means in practice — in the case of OpenBao, it may route the data to a path with stricter ACLs or audit policies.
+
+## Authentication and team sharing
+
+Harmony uses Zitadel (hosted at `sso.nationtech.io`) for identity and OpenBao (hosted at `secrets.nationtech.io`) for storage.
+
+**First run on a new machine:**
+
+1. Harmony detects that you are not logged in.
+2. It prints a short code and URL to your terminal, and opens your browser if possible.
+3. You log in with your corporate identity (Google, GitHub, or Microsoft Entra ID / Azure AD).
+4. Harmony receives an OIDC token, exchanges it for an OpenBao token, and caches the session locally.
+
+**Subsequent runs:**
+
+- Harmony silently refreshes your tokens in the background. You do not need to log in again for up to 90 days of active use.
+- If you are inactive for 30 days, or if an administrator revokes your access in Zitadel, you will be prompted to re-authenticate.
+
+**Offboarding:**
+
+Revoking a user in Zitadel immediately invalidates their ability to refresh tokens or obtain new ones. No manual secret rotation is required.
+
+## Resolution chain
+
+When Harmony resolves a config value, it tries sources in order:
+
+1. **Environment variable** (`HARMONY_CONFIG_{KEY}`) — highest priority. Use this in CI/CD to override any value without touching the store.
+2. **Config store** (OpenBao for teams, local file for solo/offline use) — the primary source for shared team state.
+3. **Interactive prompt** — last resort. Prompts the developer and persists the answer back to the store.
+
+## Schema versioning
+
+The Rust struct is the single source of truth for what configuration looks like. If a developer renames or removes a field on a branch, the store may still contain data shaped for the old version of the struct. When another developer who does not have that change runs the code, deserialization will fail.
+
+In the current implementation, this is handled gracefully: a deserialization failure is treated as a miss, and Harmony re-prompts. The new answer overwrites the stale entry.
+
+A compile-time migration mechanism is planned for a future release to handle this more rigorously at scale.
+
+## Offline and local development
+
+If you are working offline or evaluating Harmony without a team OpenBao instance, the `StoreSource` falls back to a local file store at `~/.local/share/harmony/config/`. The developer experience is identical — prompting, caching, and resolution all work the same way. The only difference is that the state is local to your machine and not shared with teammates.

docs/guides/adding-capabilities.md

@@ -0,0 +1,135 @@
+# Adding Capabilities
+
+`Capabilities` are trait methods that a `Topology` exposes to Scores. They are the "how" — the specific APIs and features that let a Score translate intent into infrastructure actions.
+
+## How Capabilities Work
+
+When a Score declares it needs certain Capabilities:
+
+```rust
+impl<T: Topology + K8sclient + HelmCommand> Score<T> for MyScore {
+    // ...
+}
+```
+
+The compiler verifies that the target `Topology` implements both `K8sclient` and `HelmCommand`. If it doesn't, compilation fails. This is the compile-time safety check that prevents invalid configurations from reaching production.
+
+## Built-in Capabilities
+
+Harmony provides a set of standard Capabilities:
+
+| Capability | What it provides |
+|------------|------------------|
+| `K8sclient` | A Kubernetes API client |
+| `HelmCommand` | A configured `helm` CLI invocation |
+| `TlsRouter` | TLS certificate management |
+| `NetworkManager` | Host network configuration |
+| `SwitchClient` | Network switch configuration |
+| `CertificateManagement` | Certificate issuance via cert-manager |
+
+## Implementing a Capability
+
+Capabilities are implemented as trait methods on your Topology:
+
+```rust
+use std::sync::Arc;
+use harmony_k8s::K8sClient;
+use harmony::topology::K8sclient;
+
+pub struct MyTopology {
+    kubeconfig: Option<String>,
+}
+
+#[async_trait]
+impl K8sclient for MyTopology {
+    async fn k8s_client(&self) -> Result<Arc<K8sClient>, String> {
+        let client = match &self.kubeconfig {
+            Some(path) => K8sClient::from_kubeconfig(path).await?,
+            None => K8sClient::try_default().await?,
+        };
+        Ok(Arc::new(client))
+    }
+}
+```
+
+## Adding a Custom Capability
+
+For specialized infrastructure needs, add your own Capability as a trait:
+
+```rust
+use async_trait::async_trait;
+use crate::executors::ExecutorError;
+
+/// A capability for configuring network switches
+#[async_trait]
+pub trait SwitchClient: Send + Sync {
+    async fn configure_port(
+        &self,
+        switch: &str,
+        port: &str,
+        vlan: u16,
+    ) -> Result<(), ExecutorError>;
+
+    async fn configure_port_channel(
+        &self,
+        switch: &str,
+        name: &str,
+        ports: &[&str],
+    ) -> Result<(), ExecutorError>;
+}
+```
+
+Then implement it on your Topology:
+
+```rust
+use harmony_infra::brocade::BrocadeClient;
+
+pub struct MyTopology {
+    switch_client: Arc<dyn SwitchClient>,
+}
+
+impl SwitchClient for MyTopology {
+    async fn configure_port(&self, switch: &str, port: &str, vlan: u16) -> Result<(), ExecutorError> {
+        self.switch_client.configure_port(switch, port, vlan).await
+    }
+
+    async fn configure_port_channel(&self, switch: &str, name: &str, ports: &[&str]) -> Result<(), ExecutorError> {
+        self.switch_client.configure_port_channel(switch, name, ports).await
+    }
+}
+```
+
+Now Scores that need `SwitchClient` can run on `MyTopology`.
+
+## Capability Composition
+
+Topologies often compose multiple Capabilities to support complex Scores:
+
+```rust
+pub struct HAClusterTopology {
+    pub kubeconfig: Option<String>,
+    pub router: Arc<dyn Router>,
+    pub load_balancer: Arc<dyn LoadBalancer>,
+    pub switch_client: Arc<dyn SwitchClient>,
+    pub dhcp_server: Arc<dyn DhcpServer>,
+    pub dns_server: Arc<dyn DnsServer>,
+    // ...
+}
+
+impl K8sclient for HAClusterTopology { ... }
+impl HelmCommand for HAClusterTopology { ... }
+impl SwitchClient for HAClusterTopology { ... }
+impl DhcpServer for HAClusterTopology { ... }
+impl DnsServer for HAClusterTopology { ... }
+impl Router for HAClusterTopology { ... }
+impl LoadBalancer for HAClusterTopology { ... }
+```
+
+A Score that needs all of these can run on `HAClusterTopology` because the Topology provides all of them.
+
+## Best Practices
+
+- **Keep Capabilities focused** — one Capability per concern (Kubernetes client, Helm, switch config)
+- **Return meaningful errors** — use specific error types so Scores can handle failures appropriately
+- **Make Capabilities optional where sensible** — not every Topology needs every Capability; use `Option<T>` or a separate trait for optional features
+- **Document preconditions** — if a Capability requires the infrastructure to be in a specific state, document it in the trait doc comments

docs/guides/developer-guide.md

@@ -0,0 +1,40 @@
+# Developer Guide
+
+This section covers how to extend Harmony by building your own `Score`, `Topology`, and `Capability` implementations.
+
+## Writing a Score
+
+A `Score` is a declarative description of desired state. To create your own:
+
+1. Define a struct that represents your desired state
+2. Implement the `Score<T>` trait, where `T` is your target `Topology`
+3. Implement the `Interpret<T>` trait to define how the Score translates to infrastructure actions
+
+See the [Writing a Score](./writing-a-score.md) guide for a step-by-step walkthrough.
+
+## Writing a Topology
+
+A `Topology` models your infrastructure environment. To create your own:
+
+1. Define a struct that holds your infrastructure configuration
+2. Implement the `Topology` trait
+3. Implement the `Capability` traits your Score needs
+
+See the [Writing a Topology](./writing-a-topology.md) guide for details.
+
+## Adding Capabilities
+
+`Capabilities` are the specific APIs or features a `Topology` exposes. They are the bridge between Scores and the actual infrastructure.
+
+See the [Adding Capabilities](./adding-capabilities.md) guide for details on implementing and exposing Capabilities.
+
+## Core Traits Reference
+
+| Trait | Purpose |
+|-------|---------|
+| `Score<T>` | Declares desired state ("what") |
+| `Topology` | Represents infrastructure ("where") |
+| `Interpret<T>` | Execution logic ("how") |
+| `Capability` | A feature exposed by a Topology |
+
+See [Core Concepts](../concepts.md) for the conceptual foundation.

docs/guides/getting-started.md

@@ -1,42 +1,230 @@
 # Getting Started Guide
 
-Welcome to Harmony! This guide will walk you through installing the Harmony framework, setting up a new project, and deploying your first application.
+This guide walks you through deploying your first application with Harmony — a PostgreSQL cluster on a local Kubernetes cluster (K3D). By the end, you'll understand the core workflow: compile a Score, run it through the Harmony CLI, and verify the result.
 
-We will build and deploy the "Rust Web App" example, which automatically:
+## What you'll deploy
 
-1. Provisions a local K3D (Kubernetes in Docker) cluster.
-2. Deploys a sample Rust web application.
-3. Sets up monitoring for the application.
+A fully functional PostgreSQL cluster running in a local K3D cluster, managed by the CloudNativePG operator. This demonstrates the full Harmony pattern:
+
+1. Provision a local Kubernetes cluster (K3D)
+2. Install the required operator (CloudNativePG)
+3. Create a PostgreSQL cluster
+4. Expose it as a Kubernetes Service
 
 ## Prerequisites
 
-Before you begin, you'll need a few tools installed on your system:
+Before you begin, install the following tools:
 
-- **Rust & Cargo:** [Install Rust](https://www.rust-lang.org/tools/install)
-- **Docker:** [Install Docker](https://docs.docker.com/get-docker/) (Required for the K3D local cluster)
-- **kubectl:** [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (For inspecting the cluster)
+- **Rust & Cargo:** [Install Rust](https://rust-lang.org/tools/install) (edition 2024)
+- **Docker:** [Install Docker](https://docs.docker.com/get-docker/) (required for the local K3D cluster)
+- **kubectl:** [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (optional, for inspecting the cluster)
 
-## 1. Install Harmony
-
-First, clone the Harmony repository and build the project. This gives you the `harmony` CLI and all the core libraries.
+## Step 1: Clone and build
 
 ```bash
-# Clone the main repository
+# Clone the repository
 git clone https://git.nationtech.io/nationtech/harmony
 cd harmony
 
-# Build the project (this may take a few minutes)
+# Build the project (this may take a few minutes on first run)
 cargo build --release
 ```
 
-...
+## Step 2: Run the PostgreSQL example
 
-## Next Steps
+```bash
+cargo run -p example-postgresql
+```
 
-Congratulations, you've just deployed an application using true infrastructure-as-code!
+Harmony will output its progress as it:
 
-From here, you can:
+1. **Creates a K3D cluster** named `harmony-postgres-example` (first run only)
+2. **Installs the CloudNativePG operator** into the cluster
+3. **Creates a PostgreSQL cluster** with 1 instance and 1 GiB of storage
+4. **Prints connection details** for your new database
 
-- [Explore the Catalogs](../catalogs/README.md): See what other [Scores](../catalogs/scores.md) and [Topologies](../catalogs/topologies.md) are available.
-- [Read the Use Cases](../use-cases/README.md): Check out the [OKD on Bare Metal](./use-cases/okd-on-bare-metal.md) guide for a more advanced scenario.
-- [Write your own Score](../guides/writing-a-score.md): Dive into the [Developer Guide](./guides/developer-guide.md) to start building your own components.
+Expected output (abbreviated):
+
+```
+[+] Cluster created
+[+] Installing CloudNativePG operator
+[+] Creating PostgreSQL cluster
+[+] PostgreSQL cluster is ready
+    Namespace: harmony-postgres-example
+    Service: harmony-postgres-example-rw
+    Username: postgres
+    Password: <stored in secret harmony-postgres-example-db-user>
+```
+
+## Step 3: Verify the deployment
+
+Check that the PostgreSQL pods are running:
+
+```bash
+kubectl get pods -n harmony-postgres-example
+```
+
+You should see something like:
+
+```
+NAME                                    READY   STATUS    RESTARTS   AGE
+harmony-postgres-example-1              1/1     Running   0          2m
+```
+
+Get the database password:
+
+```bash
+kubectl get secret -n harmony-postgres-example harmony-postgres-example-db-user -o jsonpath='{.data.password}' | base64 -d
+```
+
+## Step 4: Connect to the database
+
+Forward the PostgreSQL port to your local machine:
+
+```bash
+kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432
+```
+
+In another terminal, connect with `psql`:
+
+```bash
+psql -h localhost -p 5432 -U postgres
+# Enter the password from Step 4 when prompted
+```
+
+Try a simple query:
+
+```sql
+SELECT version();
+```
+
+## Step 5: Clean up
+
+To delete the PostgreSQL cluster and the local K3D cluster:
+
+```bash
+k3d cluster delete harmony-postgres-example
+```
+
+Alternatively, just delete the PostgreSQL cluster without removing K3D:
+
+```bash
+kubectl delete namespace harmony-postgres-example
+```
+
+## How it works
+
+The example code (`examples/postgresql/src/main.rs`) is straightforward:
+
+```rust
+use harmony::{
+    inventory::Inventory,
+    modules::postgresql::{PostgreSQLScore, capability::PostgreSQLConfig},
+    topology::K8sAnywhereTopology,
+};
+
+#[tokio::main]
+async fn main() {
+    let postgres = PostgreSQLScore {
+        config: PostgreSQLConfig {
+            cluster_name: "harmony-postgres-example".to_string(),
+            namespace: "harmony-postgres-example".to_string(),
+            ..Default::default()
+        },
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(postgres)],
+        None,
+    )
+    .await
+    .unwrap();
+}
+```
+
+- **`Inventory::autoload()`** discovers the local environment (or uses an existing inventory)
+- **`K8sAnywhereTopology::from_env()`** connects to K3D if `HARMONY_AUTOINSTALL=true` (the default), or to any Kubernetes cluster via `KUBECONFIG`
+- **`harmony_cli::run(...)`** executes the Score against the Topology, managing the full lifecycle
+
+## Connecting to an existing cluster
+
+By default, Harmony provisions a local K3D cluster. To use an existing Kubernetes cluster instead:
+
+```bash
+export KUBECONFIG=/path/to/your/kubeconfig
+export HARMONY_USE_LOCAL_K3D=false
+export HARMONY_AUTOINSTALL=false
+
+cargo run -p example-postgresql
+```
+
+## Troubleshooting
+
+### Docker is not running
+
+```
+Error: could not create cluster: docker is not running
+```
+
+Start Docker and try again.
+
+### K3D cluster creation fails
+
+```
+Error: failed to create k3d cluster
+```
+
+Ensure you have at least 2 CPU cores and 4 GiB of RAM available for Docker.
+
+### `kubectl` cannot connect to the cluster
+
+```
+error: unable to connect to a kubernetes cluster
+```
+
+After Harmony creates the cluster, it writes the kubeconfig to `~/.kube/config` or to the path in `KUBECONFIG`. Verify:
+
+```bash
+kubectl cluster-info --context k3d-harmony-postgres-example
+```
+
+### Port forward fails
+
+```
+error: unable to forward port
+```
+
+Make sure no other process is using port 5432, or use a different local port:
+
+```bash
+kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 15432:5432
+psql -h localhost -p 15432 -U postgres
+```
+
+## Next steps
+
+- [Explore the Scores Catalog](../catalogs/scores.md): See what other Scores are available
+- [Explore the Topologies Catalog](../catalogs/topologies.md): See what infrastructure Topologies are supported
+- [Read the Core Concepts](../concepts.md): Understand the Score / Topology / Interpret pattern in depth
+- [OKD on Bare Metal](../use-cases/okd-on-bare-metal.md): See a complete bare-metal deployment example
+
+## Advanced examples
+
+Once you're comfortable with the basics, these examples demonstrate more advanced use cases. Note that some require specific infrastructure (existing Kubernetes clusters, bare-metal hardware, or multi-cluster environments):
+
+| Example | Description | Prerequisites |
+|---------|-------------|---------------|
+| `monitoring` | Deploy Prometheus alerting with Discord webhooks | Existing K8s cluster |
+| `ntfy` | Deploy ntfy notification server | Existing K8s cluster |
+| `tenant` | Create a multi-tenant namespace with quotas | Existing K8s cluster |
+| `cert_manager` | Provision TLS certificates | Existing K8s cluster |
+| `validate_ceph_cluster_health` | Check Ceph cluster health | Existing Rook/Ceph cluster |
+| `okd_pxe` / `okd_installation` | Provision OKD on bare metal | HAClusterTopology, bare-metal hardware |
+
+To run any example:
+
+```bash
+cargo run -p example-<example_name>
+```

docs/guides/writing-a-score.md

@@ -0,0 +1,164 @@
+# Writing a Score
+
+A `Score` declares _what_ you want to achieve. It is decoupled from _how_ it is achieved — that logic lives in an `Interpret`.
+
+## The Pattern
+
+A Score consists of two parts:
+
+1. **A struct** — holds the configuration for your desired state
+2. **A `Score<T>` implementation** — returns an `Interpret` that knows how to execute
+
+An `Interpret` contains the actual execution logic and connects your Score to the capabilities exposed by a `Topology`.
+
+## Example: A Simple Score
+
+Here's a simplified version of `NtfyScore` from the `ntfy` module:
+
+```rust
+use async_trait::async_trait;
+use harmony::{
+    interpret::{Interpret, InterpretError, Outcome},
+    inventory::Inventory,
+    score::Score,
+    topology::{HelmCommand, K8sclient, Topology},
+};
+
+/// MyScore declares "I want to install the ntfy server"
+#[derive(Debug, Clone)]
+pub struct MyScore {
+    pub namespace: String,
+    pub host: String,
+}
+
+impl<T: Topology + HelmCommand + K8sclient> Score<T> for MyScore {
+    fn create_interpret(&self) -> Box<dyn Interpret<T>> {
+        Box::new(MyInterpret { score: self.clone() })
+    }
+
+    fn name(&self) -> String {
+        "ntfy [MyScore]".into()
+    }
+}
+
+/// MyInterpret knows _how_ to install ntfy using the Topology's capabilities
+#[derive(Debug)]
+pub struct MyInterpret {
+    pub score: MyScore,
+}
+
+#[async_trait]
+impl<T: Topology + HelmCommand + K8sclient> Interpret<T> for MyInterpret {
+    async fn execute(
+        &self,
+        inventory: &Inventory,
+        topology: &T,
+    ) -> Result<Outcome, InterpretError> {
+        // 1. Get a Kubernetes client from the Topology
+        let client = topology.k8s_client().await?;
+
+        // 2. Use Helm to install the ntfy chart
+        // (via topology's HelmCommand capability)
+
+        // 3. Wait for the deployment to be ready
+        client
+            .wait_until_deployment_ready("ntfy", Some(&self.score.namespace), None)
+            .await?;
+
+        Ok(Outcome::success("ntfy installed".to_string()))
+    }
+}
+```
+
+## The Compile-Time Safety Check
+
+The generic `Score<T>` trait is bounded by `T: Topology`. This means the compiler enforces that your Score only runs on Topologies that expose the capabilities your Interpret needs:
+
+```rust
+// This only compiles if K8sAnywhereTopology (or any T)
+// implements HelmCommand and K8sclient
+impl<T: Topology + HelmCommand + K8sclient> Score<T> for MyScore { ... }
+```
+
+If you try to run this Score against a Topology that doesn't expose `HelmCommand`, you get a compile error — before any code runs.
+
+## Using Your Score
+
+Once defined, your Score integrates with the Harmony CLI:
+
+```rust
+use harmony::{
+    inventory::Inventory,
+    topology::K8sAnywhereTopology,
+};
+
+#[tokio::main]
+async fn main() {
+    let my_score = MyScore {
+        namespace: "monitoring".to_string(),
+        host: "ntfy.example.com".to_string(),
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(my_score)],
+        None,
+    )
+    .await
+    .unwrap();
+}
+```
+
+## Key Patterns
+
+### Composing Scores
+
+Scores can include other Scores via features:
+
+```rust
+let app = ApplicationScore {
+    features: vec![
+        Box::new(PackagingDeployment { application: app.clone() }),
+        Box::new(Monitoring { application: app.clone(), alert_receiver: vec![] }),
+    ],
+    application: app,
+};
+```
+
+### Reusing Interpret Logic
+
+Many Scores delegate to shared `Interpret` implementations. For example, `HelmChartScore` provides a reusable Interpret for any Helm-based deployment. Your Score can wrap it:
+
+```rust
+impl<T: Topology + HelmCommand> Score<T> for MyScore {
+    fn create_interpret(&self) -> Box<dyn Interpret<T>> {
+        Box::new(HelmChartInterpret { /* your config */ })
+    }
+}
+```
+
+### Accessing Topology Capabilities
+
+Your Interpret accesses infrastructure through Capabilities exposed by the Topology:
+
+```rust
+// Via the Topology trait directly
+let k8s_client = topology.k8s_client().await?;
+let helm = topology.get_helm_command();
+
+// Or via Capability traits
+impl<T: Topology + K8sclient> Interpret<T> for MyInterpret {
+    async fn execute(...) {
+        let client = topology.k8s_client().await?;
+        // use client...
+    }
+}
+```
+
+## Best Practices
+
+- **Keep Scores focused** — one Score per concern (deployment, monitoring, networking)
+- **Use `..Default::default()`** for optional fields so callers only need to specify what they care about
+- **Return `Outcome`** — use `Outcome::success`, `Outcome::failure`, or `Outcome::success_with_details` to communicate results clearly
+- **Handle errors gracefully** — return meaningful `InterpretError` messages that help operators debug issues

docs/guides/writing-a-topology.md

@@ -0,0 +1,176 @@
+# Writing a Topology
+
+A `Topology` models your infrastructure environment and exposes `Capability` traits that Scores use to interact with it. Where a Score declares _what_ you want, a Topology exposes _what_ it can do.
+
+## The Minimum Implementation
+
+At minimum, a Topology needs:
+
+```rust
+use async_trait::async_trait;
+use harmony::{
+    topology::{PreparationError, PreparationOutcome, Topology},
+};
+
+#[derive(Debug, Clone)]
+pub struct MyTopology {
+    pub name: String,
+}
+
+#[async_trait]
+impl Topology for MyTopology {
+    fn name(&self) -> &str {
+        "MyTopology"
+    }
+
+    async fn ensure_ready(&self) -> Result<PreparationOutcome, PreparationError> {
+        // Verify the infrastructure is accessible and ready
+        Ok(PreparationOutcome::Success { details: "ready".to_string() })
+    }
+}
+```
+
+## Implementing Capabilities
+
+Scores express dependencies on Capabilities through trait bounds. For example, if your Topology should support Scores that deploy Helm charts, implement `HelmCommand`:
+
+```rust
+use std::process::Command;
+use harmony::topology::HelmCommand;
+
+impl HelmCommand for MyTopology {
+    fn get_helm_command(&self) -> Command {
+        let mut cmd = Command::new("helm");
+        if let Some(kubeconfig) = &self.kubeconfig {
+            cmd.arg("--kubeconfig").arg(kubeconfig);
+        }
+        cmd
+    }
+}
+```
+
+For Scores that need a Kubernetes client, implement `K8sclient`:
+
+```rust
+use std::sync::Arc;
+use harmony_k8s::K8sClient;
+use harmony::topology::K8sclient;
+
+#[async_trait]
+impl K8sclient for MyTopology {
+    async fn k8s_client(&self) -> Result<Arc<K8sClient>, String> {
+        let client = if let Some(kubeconfig) = &self.kubeconfig {
+            K8sClient::from_kubeconfig(kubeconfig).await?
+        } else {
+            K8sClient::try_default().await?
+        };
+        Ok(Arc::new(client))
+    }
+}
+```
+
+## Loading Topology from Environment
+
+For flexibility, implement `from_env()` to read configuration from environment variables:
+
+```rust
+impl MyTopology {
+    pub fn from_env() -> Self {
+        Self {
+            name: std::env::var("MY_TOPOLOGY_NAME")
+                .unwrap_or_else(|_| "default".to_string()),
+            kubeconfig: std::env::var("KUBECONFIG").ok(),
+        }
+    }
+}
+```
+
+This pattern lets operators switch between environments without recompiling:
+
+```bash
+export KUBECONFIG=/path/to/prod-cluster.kubeconfig
+cargo run --example my_example
+```
+
+## Complete Example: K8sAnywhereTopology
+
+The `K8sAnywhereTopology` is the most commonly used Topology and handles both local (K3D) and remote Kubernetes clusters:
+
+```rust
+pub struct K8sAnywhereTopology {
+    pub k8s_state: Arc<OnceCell<K8sState>>,
+    pub tenant_manager: Arc<OnceCell<TenantManager>>,
+    pub config: Arc<K8sAnywhereConfig>,
+}
+
+#[async_trait]
+impl Topology for K8sAnywhereTopology {
+    fn name(&self) -> &str {
+        "K8sAnywhereTopology"
+    }
+
+    async fn ensure_ready(&self) -> Result<PreparationOutcome, PreparationError> {
+        // 1. If autoinstall is enabled and no cluster exists, provision K3D
+        // 2. Verify kubectl connectivity
+        // 3. Optionally wait for cluster operators to be ready
+        Ok(PreparationOutcome::Success { details: "cluster ready".to_string() })
+    }
+}
+```
+
+## Key Patterns
+
+### Lazy Initialization
+
+Use `OnceCell` for expensive resources like Kubernetes clients:
+
+```rust
+pub struct K8sAnywhereTopology {
+    k8s_state: Arc<OnceCell<K8sState>>,
+}
+```
+
+### Multi-Target Topologies
+
+For Scores that span multiple clusters (like NATS supercluster), implement `MultiTargetTopology`:
+
+```rust
+pub trait MultiTargetTopology: Topology {
+    fn current_target(&self) -> &str;
+    fn set_target(&mut self, target: &str);
+}
+```
+
+### Composing Topologies
+
+Complex topologies combine multiple infrastructure components:
+
+```rust
+pub struct HAClusterTopology {
+    pub router: Arc<dyn Router>,
+    pub load_balancer: Arc<dyn LoadBalancer>,
+    pub firewall: Arc<dyn Firewall>,
+    pub dhcp_server: Arc<dyn DhcpServer>,
+    pub dns_server: Arc<dyn DnsServer>,
+    pub kubeconfig: Option<String>,
+    // ...
+}
+```
+
+## Testing Your Topology
+
+Test Topologies in isolation by implementing them against mock infrastructure:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_topology_ensure_ready() {
+        let topo = MyTopology::from_env();
+        let result = topo.ensure_ready().await;
+        assert!(result.is_ok());
+    }
+}
+```

docs/monitoring.md

@@ -1,443 +0,0 @@
-# Monitoring and Alerting in Harmony
-
-Harmony provides a unified, type-safe approach to monitoring and alerting across Kubernetes, OpenShift, and bare-metal infrastructure. This guide explains the architecture and how to use it at different levels of abstraction.
-
-## Overview
-
-Harmony's monitoring module supports three distinct use cases:
-
-| Level | Who Uses It | What It Provides |
-|-------|-------------|------------------|
-| **Cluster** | Cluster administrators | Full control over monitoring stack, cluster-wide alerts, external scrape targets |
-| **Tenant** | Platform teams | Namespace-scoped monitoring in multi-tenant environments |
-| **Application** | Application developers | Zero-config monitoring that "just works" |
-
-Each level builds on the same underlying abstractions, ensuring consistency while providing appropriate complexity for each audience.
-
-## Core Concepts
-
-### AlertSender
-
-An `AlertSender` represents the system that evaluates alert rules and sends notifications. Harmony supports multiple monitoring stacks:
-
-| Sender | Description | Use When |
-|--------|-------------|----------|
-| `OpenshiftClusterAlertSender` | OKD/OpenShift built-in monitoring | Running on OKD/OpenShift |
-| `KubePrometheus` | kube-prometheus-stack via Helm | Standard Kubernetes, need full stack |
-| `Prometheus` | Standalone Prometheus | Custom Prometheus deployment |
-| `RedHatClusterObservability` | RHOB operator | Red Hat managed clusters |
-| `Grafana` | Grafana-managed alerting | Grafana as primary alerting layer |
-
-### AlertReceiver
-
-An `AlertReceiver` defines where alerts are sent (Discord, Slack, email, webhook, etc.). Receivers are parameterized by sender type because each monitoring stack has different configuration formats.
-
-```rust
-pub trait AlertReceiver<S: AlertSender> {
-    fn build(&self) -> Result<ReceiverInstallPlan, InterpretError>;
-    fn name(&self) -> String;
-}
-```
-
-Built-in receivers:
-- `DiscordReceiver` - Discord webhooks
-- `WebhookReceiver` - Generic HTTP webhooks
-
-### AlertRule
-
-An `AlertRule` defines a Prometheus alert expression. Rules are also parameterized by sender to handle different CRD formats.
-
-```rust
-pub trait AlertRule<S: AlertSender> {
-    fn build_rule(&self) -> Result<serde_json::Value, InterpretError>;
-    fn name(&self) -> String;
-}
-```
-
-### Observability Capability
-
-Topologies implement `Observability<S>` to indicate they support a specific alert sender:
-
-```rust
-impl Observability<OpenshiftClusterAlertSender> for K8sAnywhereTopology {
-    async fn install_receivers(&self, sender, inventory, receivers) { ... }
-    async fn install_rules(&self, sender, inventory, rules) { ... }
-    // ...
-}
-```
-
-This provides **compile-time verification**: if you try to use `OpenshiftClusterAlertScore` with a topology that doesn't implement `Observability<OpenshiftClusterAlertSender>`, the code won't compile.
-
----
-
-## Level 1: Cluster Monitoring
-
-Cluster monitoring is for administrators who need full control over the monitoring infrastructure. This includes:
-- Installing/managing the monitoring stack
-- Configuring cluster-wide alert receivers
-- Defining cluster-level alert rules
-- Adding external scrape targets (e.g., bare-metal servers, firewalls)
-
-### Example: OKD Cluster Alerts
-
-```rust
-use harmony::{
-    modules::monitoring::{
-        alert_channel::discord_alert_channel::DiscordReceiver,
-        alert_rule::{alerts::k8s::pvc::high_pvc_fill_rate_over_two_days, prometheus_alert_rule::AlertManagerRuleGroup},
-        okd::openshift_cluster_alerting_score::OpenshiftClusterAlertScore,
-        scrape_target::prometheus_node_exporter::PrometheusNodeExporter,
-    },
-    topology::{K8sAnywhereTopology, monitoring::{AlertMatcher, AlertRoute, MatchOp}},
-};
-
-let severity_matcher = AlertMatcher {
-    label: "severity".to_string(),
-    operator: MatchOp::Eq,
-    value: "critical".to_string(),
-};
-
-let rule_group = AlertManagerRuleGroup::new(
-    "cluster-rules",
-    vec![high_pvc_fill_rate_over_two_days()],
-);
-
-let external_exporter = PrometheusNodeExporter {
-    job_name: "firewall".to_string(),
-    metrics_path: "/metrics".to_string(),
-    listen_address: ip!("192.168.1.1"),
-    port: 9100,
-    ..Default::default()
-};
-
-harmony_cli::run(
-    Inventory::autoload(),
-    K8sAnywhereTopology::from_env(),
-    vec![Box::new(OpenshiftClusterAlertScore {
-        sender: OpenshiftClusterAlertSender,
-        receivers: vec![Box::new(DiscordReceiver {
-            name: "critical-alerts".to_string(),
-            url: hurl!("https://discord.com/api/webhooks/..."),
-            route: AlertRoute {
-                matchers: vec![severity_matcher],
-                ..AlertRoute::default("critical-alerts".to_string())
-            },
-        })],
-        rules: vec![Box::new(rule_group)],
-        scrape_targets: Some(vec![Box::new(external_exporter)]),
-    })],
-    None,
-).await?;
-```
-
-### What This Does
-
-1. **Enables cluster monitoring** - Activates OKD's built-in Prometheus
-2. **Enables user workload monitoring** - Allows namespace-scoped rules
-3. **Configures Alertmanager** - Adds Discord receiver with route matching
-4. **Deploys alert rules** - Creates `AlertingRule` CRD with PVC fill rate alert
-5. **Adds external scrape target** - Configures Prometheus to scrape the firewall
-
-### Compile-Time Safety
-
-The `OpenshiftClusterAlertScore` requires:
-
-```rust
-impl<T: Topology + Observability<OpenshiftClusterAlertSender>> Score<T>
-    for OpenshiftClusterAlertScore
-```
-
-If `K8sAnywhereTopology` didn't implement `Observability<OpenshiftClusterAlertSender>`, this code would fail to compile. You cannot accidentally deploy OKD alerts to a cluster that doesn't support them.
-
----
-
-## Level 2: Tenant Monitoring
-
-In multi-tenant clusters, teams are often confined to specific namespaces. Tenant monitoring adapts to this constraint:
-
-- Resources are deployed in the tenant's namespace
-- Cannot modify cluster-level monitoring configuration
-- The topology determines namespace context at runtime
-
-### How It Works
-
-The topology's `Observability` implementation handles tenant scoping:
-
-```rust
-impl Observability<KubePrometheus> for K8sAnywhereTopology {
-    async fn install_rules(&self, sender, inventory, rules) {
-        // Topology knows if it's tenant-scoped
-        let namespace = self.get_tenant_config().await
-            .map(|t| t.name)
-            .unwrap_or_else(|| "monitoring".to_string());
-        
-        // Rules are installed in the appropriate namespace
-        for rule in rules.unwrap_or_default() {
-            let score = KubePrometheusRuleScore {
-                sender: sender.clone(),
-                rule,
-                namespace: namespace.clone(), // Tenant namespace
-            };
-            score.create_interpret().execute(inventory, self).await?;
-        }
-    }
-}
-```
-
-### Tenant vs Cluster Resources
-
-| Resource | Cluster-Level | Tenant-Level |
-|----------|---------------|--------------|
-| Alertmanager config | Global receivers | Namespaced receivers (where supported) |
-| PrometheusRules | Cluster-wide alerts | Namespace alerts only |
-| ServiceMonitors | Any namespace | Own namespace only |
-| External scrape targets | Can add | Cannot add (cluster config) |
-
-### Runtime Validation
-
-Tenant constraints are validated at runtime via Kubernetes RBAC. If a tenant-scoped deployment attempts cluster-level operations, it fails with a clear permission error from the Kubernetes API.
-
-This cannot be fully compile-time because tenant context is determined by who's running the code and what permissions they have—information only available at runtime.
-
----
-
-## Level 3: Application Monitoring
-
-Application monitoring provides zero-config, opinionated monitoring for developers. Just add the `Monitoring` feature to your application and it works.
-
-### Example
-
-```rust
-use harmony::modules::{
-    application::{Application, ApplicationFeature},
-    monitoring::alert_channel::webhook_receiver::WebhookReceiver,
-};
-
-// Define your application
-let my_app = MyApplication::new();
-
-// Add monitoring as a feature
-let monitoring = Monitoring {
-    application: Arc::new(my_app),
-    alert_receiver: vec![], // Uses defaults
-};
-
-// Install with the application
-my_app.add_feature(monitoring);
-```
-
-### What Application Monitoring Provides
-
-1. **Automatic ServiceMonitor** - Creates a ServiceMonitor for your application's pods
-2. **Ntfy Notification Channel** - Auto-installs and configures Ntfy for push notifications
-3. **Tenant Awareness** - Automatically scopes to the correct namespace
-4. **Sensible Defaults** - Pre-configured alert routes and receivers
-
-### Under the Hood
-
-```rust
-impl<T: Topology + Observability<Prometheus> + TenantManager> 
-    ApplicationFeature<T> for Monitoring 
-{
-    async fn ensure_installed(&self, topology: &T) -> Result<...> {
-        // 1. Get tenant namespace (or use app name)
-        let namespace = topology.get_tenant_config().await
-            .map(|ns| ns.name.clone())
-            .unwrap_or_else(|| self.application.name());
-
-        // 2. Create ServiceMonitor for the app
-        let app_service_monitor = ServiceMonitor {
-            metadata: ObjectMeta {
-                name: Some(self.application.name()),
-                namespace: Some(namespace.clone()),
-                ..Default::default()
-            },
-            spec: ServiceMonitorSpec::default(),
-        };
-
-        // 3. Install Ntfy for notifications
-        let ntfy = NtfyScore { namespace, host };
-        ntfy.interpret(&Inventory::empty(), topology).await?;
-
-        // 4. Wire up webhook receiver to Ntfy
-        let ntfy_receiver = WebhookReceiver { ... };
-        
-        // 5. Execute monitoring score
-        alerting_score.interpret(&Inventory::empty(), topology).await?;
-    }
-}
-```
-
----
-
-## Pre-Built Alert Rules
-
-Harmony provides a library of common alert rules in `modules/monitoring/alert_rule/alerts/`:
-
-### Kubernetes Alerts (`alerts/k8s/`)
-
-```rust
-use harmony::modules::monitoring::alert_rule::alerts::k8s::{
-    pod::pod_failed,
-    pvc::high_pvc_fill_rate_over_two_days,
-    memory_usage::alert_high_memory_usage,
-};
-
-let rules = AlertManagerRuleGroup::new("k8s-rules", vec![
-    pod_failed(),
-    high_pvc_fill_rate_over_two_days(),
-    alert_high_memory_usage(),
-]);
-```
-
-Available rules:
-- `pod_failed()` - Pod in failed state
-- `alert_container_restarting()` - Container restart loop
-- `alert_pod_not_ready()` - Pod not ready for extended period
-- `high_pvc_fill_rate_over_two_days()` - PVC will fill within 2 days
-- `alert_high_memory_usage()` - Memory usage above threshold
-- `alert_high_cpu_usage()` - CPU usage above threshold
-
-### Infrastructure Alerts (`alerts/infra/`)
-
-```rust
-use harmony::modules::monitoring::alert_rule::alerts::infra::opnsense::high_http_error_rate;
-
-let rules = AlertManagerRuleGroup::new("infra-rules", vec![
-    high_http_error_rate(),
-]);
-```
-
-### Creating Custom Rules
-
-```rust
-use harmony::modules::monitoring::alert_rule::prometheus_alert_rule::PrometheusAlertRule;
-
-pub fn my_custom_alert() -> PrometheusAlertRule {
-    PrometheusAlertRule::new("MyServiceDown", "up{job=\"my-service\"} == 0")
-        .for_duration("5m")
-        .label("severity", "critical")
-        .annotation("summary", "My service is down")
-        .annotation("description", "The my-service job has been down for more than 5 minutes")
-}
-```
-
----
-
-## Alert Receivers
-
-### Discord Webhook
-
-```rust
-use harmony::modules::monitoring::alert_channel::discord_alert_channel::DiscordReceiver;
-use harmony::topology::monitoring::{AlertRoute, AlertMatcher, MatchOp};
-
-let discord = DiscordReceiver {
-    name: "ops-alerts".to_string(),
-    url: hurl!("https://discord.com/api/webhooks/123456/abcdef"),
-    route: AlertRoute {
-        receiver: "ops-alerts".to_string(),
-        matchers: vec![AlertMatcher {
-            label: "severity".to_string(),
-            operator: MatchOp::Eq,
-            value: "critical".to_string(),
-        }],
-        group_by: vec!["alertname".to_string()],
-        repeat_interval: Some("30m".to_string()),
-        continue_matching: false,
-        children: vec![],
-    },
-};
-```
-
-### Generic Webhook
-
-```rust
-use harmony::modules::monitoring::alert_channel::webhook_receiver::WebhookReceiver;
-
-let webhook = WebhookReceiver {
-    name: "custom-webhook".to_string(),
-    url: hurl!("https://api.example.com/alerts"),
-    route: AlertRoute::default("custom-webhook".to_string()),
-};
-```
-
----
-
-## Adding a New Monitoring Stack
-
-To add support for a new monitoring stack:
-
-1. **Create the sender type** in `modules/monitoring/my_sender/mod.rs`:
-   ```rust
-   #[derive(Debug, Clone)]
-   pub struct MySender;
-   
-   impl AlertSender for MySender {
-       fn name(&self) -> String { "MySender".to_string() }
-   }
-   ```
-
-2. **Define CRD types** in `modules/monitoring/my_sender/crd/`:
-   ```rust
-   #[derive(CustomResource, Debug, Serialize, Deserialize, Clone)]
-   #[kube(group = "monitoring.example.com", version = "v1", kind = "MyAlertRule")]
-   pub struct MyAlertRuleSpec { ... }
-   ```
-
-3. **Implement Observability** in `domain/topology/k8s_anywhere/observability/my_sender.rs`:
-   ```rust
-   impl Observability<MySender> for K8sAnywhereTopology {
-       async fn install_receivers(&self, sender, inventory, receivers) { ... }
-       async fn install_rules(&self, sender, inventory, rules) { ... }
-       // ...
-   }
-   ```
-
-4. **Implement receiver conversions** for existing receivers:
-   ```rust
-   impl AlertReceiver<MySender> for DiscordReceiver {
-       fn build(&self) -> Result<ReceiverInstallPlan, InterpretError> {
-           // Convert DiscordReceiver to MySender's format
-       }
-   }
-   ```
-
-5. **Create score types**:
-   ```rust
-   pub struct MySenderAlertScore {
-       pub sender: MySender,
-       pub receivers: Vec<Box<dyn AlertReceiver<MySender>>>,
-       pub rules: Vec<Box<dyn AlertRule<MySender>>>,
-   }
-   ```
-
----
-
-## Architecture Principles
-
-### Type Safety Over Flexibility
-
-Each monitoring stack has distinct CRDs and configuration formats. Rather than a unified "MonitoringStack" type that loses stack-specific features, we use generic traits that provide type safety while allowing each stack to express its unique configuration.
-
-### Compile-Time Capability Verification
-
-The `Observability<S>` bound ensures you can't deploy OKD alerts to a KubePrometheus cluster. The compiler catches platform mismatches before deployment.
-
-### Explicit Over Implicit
-
-Monitoring stacks are chosen explicitly (`OpenshiftClusterAlertSender` vs `KubePrometheus`). There's no "auto-detection" that could lead to surprising behavior.
-
-### Three Levels, One Foundation
-
-Cluster, tenant, and application monitoring all use the same traits (`AlertSender`, `AlertReceiver`, `AlertRule`). The difference is in how scores are constructed and how topologies interpret them.
-
----
-
-## Related Documentation
-
-- [ADR-020: Monitoring and Alerting Architecture](../adr/020-monitoring-alerting-architecture.md)
-- [ADR-013: Monitoring Notifications (ntfy)](../adr/013-monitoring-notifications.md)
-- [ADR-011: Multi-Tenant Cluster Architecture](../adr/011-multi-tenant-cluster.md)
-- [Coding Guide](coding-guide.md)
-- [Core Concepts](concepts.md)

docs/use-cases/README.md

@@ -0,0 +1,17 @@
+# Use Cases
+
+Real-world scenarios demonstrating Harmony in action.
+
+## Available Use Cases
+
+### [PostgreSQL on Local K3D](./postgresql-on-local-k3d.md)
+
+Deploy a fully functional PostgreSQL cluster on a local K3D cluster in under 10 minutes. The quickest way to see Harmony in action.
+
+### [OKD on Bare Metal](./okd-on-bare-metal.md)
+
+A complete walkthrough of bootstrapping a high-availability OKD cluster from physical hardware. Covers inventory discovery, bootstrap, control plane, and worker provisioning.
+
+---
+
+_These use cases are community-tested scenarios. For questions or contributions, open an issue on the [Harmony repository](https://git.nationtech.io/NationTech/harmony/issues)._

docs/use-cases/okd-on-bare-metal.md

@@ -0,0 +1,159 @@
+# Use Case: OKD on Bare Metal
+
+Provision a production-grade OKD (OpenShift Kubernetes Distribution) cluster from physical hardware using Harmony. This use case covers the full lifecycle: hardware discovery, bootstrap, control plane, workers, and post-install validation.
+
+## What you'll have at the end
+
+A highly-available OKD cluster with:
+- 3 control plane nodes
+- 2+ worker nodes
+- Network bonding configured on nodes and switches
+- Load balancer routing API and ingress traffic
+- DNS and DHCP services for the cluster
+- Post-install health validation
+
+## Target hardware model
+
+This setup assumes a typical lab environment:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Network 192.168.x.0/24 (flat, DHCP + PXE capable)     │
+│                                                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
+│  │  cp0     │  │  cp1     │  │  cp2     │  (control) │
+│  └──────────┘  └──────────┘  └──────────┘            │
+│  ┌──────────┐  ┌──────────┐                            │
+│  │  wk0     │  │  wk1     │  ...        (workers)    │
+│  └──────────┘  └──────────┘                            │
+│  ┌──────────┐                                          │
+│  │ bootstrap│  (temporary, can be repurposed)          │
+│  └──────────┘                                          │
+│                                                         │
+│  ┌──────────┐  ┌──────────┐                            │
+│  │ firewall │  │  switch  │  (OPNsense + Brocade)     │
+│  └──────────┘  └──────────┘                            │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Required infrastructure
+
+Harmony models this as an `HAClusterTopology`, which requires these capabilities:
+
+| Capability | Implementation |
+|------------|---------------|
+| **Router** | OPNsense firewall |
+| **Load Balancer** | OPNsense HAProxy |
+| **Firewall** | OPNsense |
+| **DHCP Server** | OPNsense |
+| **TFTP Server** | OPNsense |
+| **HTTP Server** | OPNsense |
+| **DNS Server** | OPNsense |
+| **Node Exporter** | Prometheus node_exporter on OPNsense |
+| **Switch Client** | Brocade SNMP |
+
+See `examples/okd_installation/` for a reference topology implementation.
+
+## The Provisioning Pipeline
+
+Harmony orchestrates OKD installation in ordered stages:
+
+### Stage 1: Inventory Discovery (`OKDSetup01InventoryScore`)
+
+Harmony boots all nodes via PXE into a CentOS Stream live environment, runs an inventory agent on each, and collects:
+- MAC addresses and NIC details
+- IP addresses assigned by DHCP
+- Hardware profile (CPU, RAM, storage)
+
+This is the "discovery-first" approach: no pre-configuration required on nodes.
+
+### Stage 2: Bootstrap Node (`OKDSetup02BootstrapScore`)
+
+The user selects one discovered node to serve as the bootstrap node. Harmony:
+- Renders per-MAC iPXE boot configuration with OKD 4.19 SCOS live assets + ignition
+- Reboots the bootstrap node via SSH
+- Waits for the bootstrap process to complete (API server becomes available)
+
+### Stage 3: Control Plane (`OKDSetup03ControlPlaneScore`)
+
+With bootstrap complete, Harmony provisions the control plane nodes:
+- Renders per-MAC iPXE for each control plane node
+- Reboots via SSH and waits for node to join the cluster
+- Applies network bond configuration via NMState MachineConfig where relevant
+
+### Stage 4: Network Bonding (`OKDSetupPersistNetworkBondScore`)
+
+Configures LACP bonds on nodes and corresponding port-channels on the switch stack for high-availability.
+
+### Stage 5: Worker Nodes (`OKDSetup04WorkersScore`)
+
+Provisions worker nodes similarly to control plane, joining them to the cluster.
+
+### Stage 6: Sanity Check (`OKDSetup05SanityCheckScore`)
+
+Validates:
+- API server is reachable
+- Ingress controller is operational
+- Cluster operators are healthy
+- SDN (software-defined networking) is functional
+
+### Stage 7: Installation Report (`OKDSetup06InstallationReportScore`)
+
+Produces a machine-readable JSON report and human-readable summary of the installation.
+
+## Network notes
+
+**During discovery:** Ports must be in access mode (no LACP). DHCP succeeds; iPXE loads CentOS Stream live with Kickstart and starts the inventory endpoint.
+
+**During provisioning:** After SCOS is on disk and Ignition/MachineConfig can be applied, bonds are set persistently. This avoids the PXE/DHCP recovery race condition that occurs if bonding is configured too early.
+
+**PXE limitation:** The generic discovery path cannot use bonded networks for PXE boot because the DHCP recovery process conflicts with bond formation.
+
+## Configuration knobs
+
+When using `OKDInstallationPipeline`, configure these domains:
+
+| Parameter | Example | Description |
+|-----------|---------|-------------|
+| `public_domain` | `apps.example.com` | Wildcard domain for application ingress |
+| `internal_domain` | `cluster.local` | Internal cluster DNS domain |
+
+## Running the example
+
+See `examples/okd_installation/` for a complete reference. The topology must be configured with your infrastructure details:
+
+```bash
+# Configure the example with your hardware/network specifics
+# See examples/okd_installation/src/topology.rs
+
+cargo run -p example-okd_installation
+```
+
+This example requires:
+- Physical hardware configured as described above
+- OPNsense firewall with SSH access
+- Brocade switch with SNMP access
+- All nodes connected to the same Layer 2 network
+
+## Post-install
+
+After the cluster is bootstrapped, `~/.kube/config` is updated with the cluster credentials. Verify:
+
+```bash
+kubectl get nodes
+kubectl get pods -n openshift-monitoring
+oc get routes -n openshift-console
+```
+
+## Next steps
+
+- Enable monitoring with `PrometheusAlertScore` or `OpenshiftClusterAlertScore`
+- Configure TLS certificates with `CertManagerHelmScore`
+- Add storage with Rook Ceph
+- Scale workers with `OKDSetup04WorkersScore`
+
+## Further reading
+
+- [OKD Installation Module](../../harmony/src/modules/okd/installation.rs) — source of truth for pipeline stages
+- [HAClusterTopology](../../harmony/src/domain/topology/ha_cluster.rs) — infrastructure capability model
+- [Scores Catalog](../catalogs/scores.md) — all available Scores including OKD-specific ones

docs/use-cases/postgresql-on-local-k3d.md

@@ -0,0 +1,115 @@
+# Use Case: PostgreSQL on Local K3D
+
+Deploy a production-grade PostgreSQL cluster on a local Kubernetes cluster (K3D) using Harmony. This is the fastest way to get started with Harmony and requires no external infrastructure.
+
+## What you'll have at the end
+
+A fully operational PostgreSQL cluster with:
+- 1 primary instance with 1 GiB of storage
+- CloudNativePG operator managing the cluster lifecycle
+- Automatic failover support (foundation for high-availability)
+- Exposed as a Kubernetes Service for easy connection
+
+## Prerequisites
+
+- Rust 2024 edition
+- Docker running locally
+- ~5 minutes
+
+## The Score
+
+The entire deployment is expressed in ~20 lines of Rust:
+
+```rust
+use harmony::{
+    inventory::Inventory,
+    modules::postgresql::{PostgreSQLScore, capability::PostgreSQLConfig},
+    topology::K8sAnywhereTopology,
+};
+
+#[tokio::main]
+async fn main() {
+    let postgres = PostgreSQLScore {
+        config: PostgreSQLConfig {
+            cluster_name: "harmony-postgres-example".to_string(),
+            namespace: "harmony-postgres-example".to_string(),
+            ..Default::default()
+        },
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(postgres)],
+        None,
+    )
+    .await
+    .unwrap();
+}
+```
+
+## What Harmony does
+
+When you run this, Harmony:
+
+1. **Connects to K8sAnywhereTopology** — this auto-provisions a K3D cluster if none exists
+2. **Installs the CloudNativePG operator** — one-time setup that enables PostgreSQL cluster management in Kubernetes
+3. **Creates a PostgreSQL cluster** — Harmony translates the Score into a `Cluster` CRD and applies it
+4. **Exposes the database** — creates a Kubernetes Service for the PostgreSQL primary
+
+## Running it
+
+```bash
+cargo run -p example-postgresql
+```
+
+## Verifying the deployment
+
+```bash
+# Check pods
+kubectl get pods -n harmony-postgres-example
+
+# Get the password
+PASSWORD=$(kubectl get secret -n harmony-postgres-example \
+  harmony-postgres-example-db-user \
+  -o jsonpath='{.data.password}' | base64 -d)
+
+# Connect via port-forward
+kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432
+psql -h localhost -p 5432 -U postgres -W "$PASSWORD"
+```
+
+## Customizing the deployment
+
+The `PostgreSQLConfig` struct supports:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `cluster_name` | — | Name of the PostgreSQL cluster |
+| `namespace` | — | Kubernetes namespace to deploy to |
+| `instances` | `1` | Number of instances |
+| `storage_size` | `1Gi` | Persistent storage size per instance |
+
+Example with custom settings:
+
+```rust
+let postgres = PostgreSQLScore {
+    config: PostgreSQLConfig {
+        cluster_name: "my-prod-db".to_string(),
+        namespace: "database".to_string(),
+        instances: 3,
+        storage_size: "10Gi".to_string().into(),
+        ..Default::default()
+    },
+};
+```
+
+## Extending the pattern
+
+This pattern extends to any Kubernetes-native workload:
+
+- Add **monitoring** by including a `Monitoring` feature alongside your Score
+- Add **TLS certificates** by including a `CertificateScore`
+- Add **tenant isolation** by wrapping in a `TenantScore`
+
+See [Scores Catalog](../catalogs/scores.md) for the full list.

examples/README.md

@@ -0,0 +1,127 @@
+# Examples
+
+This directory contains runnable examples demonstrating Harmony's capabilities. Each example is a self-contained program that can be run with `cargo run -p example-<name>`.
+
+## Quick Reference
+
+| Example | Description | Local K3D | Existing Cluster | Hardware Needed |
+|---------|-------------|:---------:|:----------------:|:---------------:|
+| `postgresql` | Deploy a PostgreSQL cluster | ✅ | ✅ | — |
+| `ntfy` | Deploy ntfy notification server | ✅ | ✅ | — |
+| `tenant` | Create a multi-tenant namespace | ✅ | ✅ | — |
+| `cert_manager` | Provision TLS certificates | ✅ | ✅ | — |
+| `node_health` | Check Kubernetes node health | ✅ | ✅ | — |
+| `monitoring` | Deploy Prometheus alerting | ✅ | ✅ | — |
+| `monitoring_with_tenant` | Monitoring + tenant isolation | ✅ | ✅ | — |
+| `operatorhub_catalog` | Install OperatorHub catalog | ✅ | ✅ | — |
+| `validate_ceph_cluster_health` | Verify Ceph cluster health | — | ✅ | Rook/Ceph |
+| `remove_rook_osd` | Remove a Rook OSD | — | ✅ | Rook/Ceph |
+| `brocade_snmp_server` | Configure Brocade switch SNMP | — | ✅ | Brocade switch |
+| `opnsense_node_exporter` | Node exporter on OPNsense | — | ✅ | OPNsense firewall |
+| `okd_pxe` | PXE boot configuration for OKD | — | — | ✅ |
+| `okd_installation` | Full OKD bare-metal install | — | — | ✅ |
+| `okd_cluster_alerts` | OKD cluster monitoring alerts | — | ✅ | OKD cluster |
+| `multisite_postgres` | Multi-site PostgreSQL failover | — | ✅ | Multi-cluster |
+| `nats` | Deploy NATS messaging | — | ✅ | Multi-cluster |
+| `nats-supercluster` | NATS supercluster across sites | — | ✅ | Multi-cluster |
+| `lamp` | LAMP stack deployment | ✅ | ✅ | — |
+| `openbao` | Deploy OpenBao vault | ✅ | ✅ | — |
+| `zitadel` | Deploy Zitadel identity provider | ✅ | ✅ | — |
+| `try_rust_webapp` | Rust webapp with packaging | ✅ | ✅ | Submodule |
+| `rust` | Rust webapp with full monitoring | ✅ | ✅ | — |
+| `rhob_application_monitoring` | RHOB monitoring setup | ✅ | ✅ | — |
+| `sttest` | Full OKD stack test | — | — | ✅ |
+| `application_monitoring_with_tenant` | App monitoring + tenant | — | ✅ | OKD cluster |
+| `kube-rs` | Direct kube-rs client usage | ✅ | ✅ | — |
+| `k8s_drain_node` | Drain a Kubernetes node | ✅ | ✅ | — |
+| `k8s_write_file_on_node` | Write files to K8s nodes | ✅ | ✅ | — |
+| `harmony_inventory_builder` | Discover hosts via subnet scan | ✅ | — | — |
+| `cli` | CLI tool with inventory discovery | ✅ | — | — |
+| `tui` | Terminal UI demonstration | ✅ | — | — |
+
+## Status Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Works out-of-the-box |
+| — | Not applicable or requires specific setup |
+
+## By Category
+
+### Data Services
+- **`postgresql`** — Deploy a PostgreSQL cluster via CloudNativePG
+- **`multisite_postgres`** — Multi-site PostgreSQL with failover
+- **`public_postgres`** — Public-facing PostgreSQL (⚠️ uses NationTech DNS)
+
+### Kubernetes Utilities
+- **`node_health`** — Check node health in a cluster
+- **`k8s_drain_node`** — Drain and reboot a node
+- **`k8s_write_file_on_node`** — Write files to nodes
+- **`validate_ceph_cluster_health`** — Verify Ceph/Rook cluster health
+- **`remove_rook_osd`** — Remove an OSD from Rook/Ceph
+- **`kube-rs`** — Direct Kubernetes client usage demo
+
+### Monitoring & Alerting
+- **`monitoring`** — Deploy Prometheus alerting with Discord webhooks
+- **`monitoring_with_tenant`** — Monitoring with tenant isolation
+- **`ntfy`** — Deploy ntfy notification server
+- **`okd_cluster_alerts`** — OKD-specific cluster alerts
+
+### Application Deployment
+- **`try_rust_webapp`** — Deploy a Rust webapp with packaging (⚠️ requires `tryrust.org` submodule)
+- **`rust`** — Rust webapp with full monitoring features
+- **`rhob_application_monitoring`** — Red Hat Observability Stack monitoring
+- **`lamp`** — LAMP stack deployment (⚠️ uses NationTech DNS)
+- **`application_monitoring_with_tenant`** — App monitoring with tenant isolation
+
+### Infrastructure & Bare Metal
+- **`okd_installation`** — Full OKD cluster from scratch
+- **`okd_pxe`** — PXE boot configuration for OKD
+- **`sttest`** — Full OKD stack test with specific hardware
+- **`brocade_snmp_server`** — Configure Brocade switch via SNMP
+- **`opnsense_node_exporter`** — Node exporter on OPNsense firewall
+
+### Multi-Cluster
+- **`nats`** — NATS deployment on a cluster
+- **`nats-supercluster`** — NATS supercluster across multiple sites
+- **`multisite_postgres`** — PostgreSQL with multi-site failover
+
+### Identity & Secrets
+- **`openbao`** — Deploy OpenBao vault (⚠️ uses NationTech DNS)
+- **`zitadel`** — Deploy Zitadel identity provider (⚠️ uses NationTech DNS)
+
+### Cluster Services
+- **`cert_manager`** — Provision TLS certificates
+- **`tenant`** — Create a multi-tenant namespace
+- **`operatorhub_catalog`** — Install OperatorHub catalog sources
+
+### Development & Testing
+- **`cli`** — CLI tool with inventory discovery
+- **`tui`** — Terminal UI demonstration
+- **`harmony_inventory_builder`** — Host discovery via subnet scan
+
+## Running Examples
+
+```bash
+# Build first
+cargo build --release
+
+# Run any example
+cargo run -p example-postgresql
+cargo run -p example-ntfy
+cargo run -p example-tenant
+```
+
+For examples that need an existing Kubernetes cluster:
+
+```bash
+export KUBECONFIG=/path/to/your/kubeconfig
+export HARMONY_USE_LOCAL_K3D=false
+export HARMONY_AUTOINSTALL=false
+
+cargo run -p example-monitoring
+```
+
+## Notes on Private Infrastructure
+
+Some examples use NationTech-hosted infrastructure by default (DNS domains like `*.nationtech.io`, `*.harmony.mcd`). These are not suitable for public use without modification. See the [Getting Started Guide](../docs/guides/getting-started.md) for the recommended public examples.

examples/application_monitoring_with_tenant/src/main.rs

@@ -7,7 +7,7 @@ use harmony::{
         monitoring::alert_channel::webhook_receiver::WebhookReceiver,
         tenant::TenantScore,
     },
-    topology::{K8sAnywhereTopology, monitoring::AlertRoute, tenant::TenantConfig},
+    topology::{K8sAnywhereTopology, tenant::TenantConfig},
 };
 use harmony_types::id::Id;
 use harmony_types::net::Url;
@@ -33,14 +33,9 @@ async fn main() {
         service_port: 3000,
     });
 
-    let receiver_name = "sample-webhook-receiver".to_string();
-
     let webhook_receiver = WebhookReceiver {
-        name: receiver_name.clone(),
+        name: "sample-webhook-receiver".to_string(),
         url: Url::Url(url::Url::parse("https://webhook-doesnt-exist.com").unwrap()),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
     };
 
     let app = ApplicationScore {

examples/monitoring/src/main.rs

@@ -1,45 +1,37 @@
-use std::{
-    collections::HashMap,
-    sync::{Arc, Mutex},
-};
+use std::collections::HashMap;
 
 use harmony::{
     inventory::Inventory,
-    modules::monitoring::{
-        alert_channel::discord_alert_channel::DiscordReceiver,
-        alert_rule::{
-            alerts::{
-                infra::dell_server::{
-                    alert_global_storage_status_critical,
-                    alert_global_storage_status_non_recoverable,
-                    global_storage_status_degraded_non_critical,
+    modules::{
+        monitoring::{
+            alert_channel::discord_alert_channel::DiscordWebhook,
+            alert_rule::prometheus_alert_rule::AlertManagerRuleGroup,
+            kube_prometheus::{
+                helm_prometheus_alert_score::HelmPrometheusAlertingScore,
+                types::{
+                    HTTPScheme, MatchExpression, Operator, Selector, ServiceMonitor,
+                    ServiceMonitorEndpoint,
                 },
-                k8s::pvc::high_pvc_fill_rate_over_two_days,
             },
-            prometheus_alert_rule::AlertManagerRuleGroup,
         },
-        kube_prometheus::{
-            helm::config::KubePrometheusConfig,
-            kube_prometheus_alerting_score::KubePrometheusAlertingScore,
-            types::{
-                HTTPScheme, MatchExpression, Operator, Selector, ServiceMonitor,
-                ServiceMonitorEndpoint,
+        prometheus::alerts::{
+            infra::dell_server::{
+                alert_global_storage_status_critical, alert_global_storage_status_non_recoverable,
+                global_storage_status_degraded_non_critical,
             },
+            k8s::pvc::high_pvc_fill_rate_over_two_days,
         },
     },
-    topology::{K8sAnywhereTopology, monitoring::AlertRoute},
+    topology::K8sAnywhereTopology,
 };
 use harmony_types::{k8s_name::K8sName, net::Url};
 
 #[tokio::main]
 async fn main() {
-    let receiver_name = "test-discord".to_string();
-    let discord_receiver = DiscordReceiver {
-        name: receiver_name.clone(),
+    let discord_receiver = DiscordWebhook {
+        name: K8sName("test-discord".to_string()),
         url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
+        selectors: vec![],
     };
 
     let high_pvc_fill_rate_over_two_days_alert = high_pvc_fill_rate_over_two_days();
@@ -78,15 +70,10 @@ async fn main() {
         endpoints: vec![service_monitor_endpoint],
         ..Default::default()
     };
-
-    let config = Arc::new(Mutex::new(KubePrometheusConfig::new()));
-
-    let alerting_score = KubePrometheusAlertingScore {
+    let alerting_score = HelmPrometheusAlertingScore {
         receivers: vec![Box::new(discord_receiver)],
         rules: vec![Box::new(additional_rules), Box::new(additional_rules2)],
         service_monitors: vec![service_monitor],
-        scrape_targets: None,
-        config,
     };
 
     harmony_cli::run(

examples/monitoring_with_tenant/src/main.rs

@@ -1,32 +1,24 @@
-use std::{
-    collections::HashMap,
-    str::FromStr,
-    sync::{Arc, Mutex},
-};
+use std::{collections::HashMap, str::FromStr};
 
 use harmony::{
     inventory::Inventory,
     modules::{
         monitoring::{
-            alert_channel::discord_alert_channel::DiscordReceiver,
-            alert_rule::{
-                alerts::k8s::pvc::high_pvc_fill_rate_over_two_days,
-                prometheus_alert_rule::AlertManagerRuleGroup,
-            },
+            alert_channel::discord_alert_channel::DiscordWebhook,
+            alert_rule::prometheus_alert_rule::AlertManagerRuleGroup,
             kube_prometheus::{
-                helm::config::KubePrometheusConfig,
-                kube_prometheus_alerting_score::KubePrometheusAlertingScore,
+                helm_prometheus_alert_score::HelmPrometheusAlertingScore,
                 types::{
                     HTTPScheme, MatchExpression, Operator, Selector, ServiceMonitor,
                     ServiceMonitorEndpoint,
                 },
             },
         },
+        prometheus::alerts::k8s::pvc::high_pvc_fill_rate_over_two_days,
         tenant::TenantScore,
     },
     topology::{
         K8sAnywhereTopology,
-        monitoring::AlertRoute,
         tenant::{ResourceLimits, TenantConfig, TenantNetworkPolicy},
     },
 };
@@ -50,13 +42,10 @@ async fn main() {
         },
     };
 
-    let receiver_name = "test-discord".to_string();
-    let discord_receiver = DiscordReceiver {
-        name: receiver_name.clone(),
+    let discord_receiver = DiscordWebhook {
+        name: K8sName("test-discord".to_string()),
         url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
+        selectors: vec![],
     };
 
     let high_pvc_fill_rate_over_two_days_alert = high_pvc_fill_rate_over_two_days();
@@ -85,14 +74,10 @@ async fn main() {
         ..Default::default()
     };
 
-    let config = Arc::new(Mutex::new(KubePrometheusConfig::new()));
-
-    let alerting_score = KubePrometheusAlertingScore {
+    let alerting_score = HelmPrometheusAlertingScore {
         receivers: vec![Box::new(discord_receiver)],
         rules: vec![Box::new(additional_rules)],
         service_monitors: vec![service_monitor],
-        scrape_targets: None,
-        config,
     };
 
     harmony_cli::run(

examples/multisite_postgres/src/main.rs

@@ -14,7 +14,6 @@ async fn main() {
             ..Default::default() // Use harmony defaults, they are based on CNPG's default values :
                                  // "default" namespace, 1 instance, 1Gi storage
         },
-        hostname: "postgrestest.sto1.nationtech.io".to_string(),
     };
 
     harmony_cli::run(

examples/okd_cluster_alerts/src/main.rs

@@ -1,64 +1,35 @@
+use std::collections::HashMap;
+
 use harmony::{
     inventory::Inventory,
     modules::monitoring::{
-        alert_channel::discord_alert_channel::DiscordReceiver,
-        alert_rule::{
-            alerts::{
-                infra::opnsense::high_http_error_rate, k8s::pvc::high_pvc_fill_rate_over_two_days,
-            },
-            prometheus_alert_rule::AlertManagerRuleGroup,
-        },
-        okd::openshift_cluster_alerting_score::OpenshiftClusterAlertScore,
-        scrape_target::prometheus_node_exporter::PrometheusNodeExporter,
-    },
-    topology::{
-        K8sAnywhereTopology,
-        monitoring::{AlertMatcher, AlertRoute, MatchOp},
+        alert_channel::discord_alert_channel::DiscordWebhook,
+        okd::cluster_monitoring::OpenshiftClusterAlertScore,
     },
+    topology::K8sAnywhereTopology,
 };
-
-use harmony_macros::{hurl, ip};
+use harmony_macros::hurl;
+use harmony_types::k8s_name::K8sName;
 
 #[tokio::main]
 async fn main() {
-    let platform_matcher = AlertMatcher {
-        label: "prometheus".to_string(),
-        operator: MatchOp::Eq,
-        value: "openshift-monitoring/k8s".to_string(),
-    };
-    let severity = AlertMatcher {
-        label: "severity".to_string(),
-        operator: MatchOp::Eq,
-        value: "critical".to_string(),
-    };
-
-    let high_http_error_rate = high_http_error_rate();
-
-    let additional_rules = AlertManagerRuleGroup::new("test-rule", vec![high_http_error_rate]);
-
-    let scrape_target = PrometheusNodeExporter {
-        job_name: "firewall".to_string(),
-        metrics_path: "/metrics".to_string(),
-        listen_address: ip!("192.168.1.1"),
-        port: 9100,
-        ..Default::default()
-    };
-
+    let mut sel = HashMap::new();
+    sel.insert(
+        "openshift_io_alert_source".to_string(),
+        "platform".to_string(),
+    );
+    let mut sel2 = HashMap::new();
+    sel2.insert("openshift_io_alert_source".to_string(), "".to_string());
+    let selectors = vec![sel, sel2];
     harmony_cli::run(
         Inventory::autoload(),
         K8sAnywhereTopology::from_env(),
         vec![Box::new(OpenshiftClusterAlertScore {
-            receivers: vec![Box::new(DiscordReceiver {
-                name: "crit-wills-discord-channel-example".to_string(),
-                url: hurl!("https://test.io"),
-                route: AlertRoute {
-                    matchers: vec![severity],
-                    ..AlertRoute::default("crit-wills-discord-channel-example".to_string())
-                },
+            receivers: vec![Box::new(DiscordWebhook {
+                name: K8sName("wills-discord-webhook-example".to_string()),
+                url: hurl!("https://something.io"),
+                selectors: selectors,
             })],
-            sender: harmony::modules::monitoring::okd::OpenshiftClusterAlertSender,
-            rules: vec![Box::new(additional_rules)],
-            scrape_targets: Some(vec![Box::new(scrape_target)]),
         })],
         None,
     )

examples/okd_installation/src/main.rs

@@ -6,7 +6,10 @@ use harmony::{
     data::{FileContent, FilePath},
     modules::{
         inventory::HarmonyDiscoveryStrategy,
-        okd::{installation::OKDInstallationPipeline, ipxe::OKDIpxeScore},
+        okd::{
+            installation::OKDInstallationPipeline, ipxe::OKDIpxeScore,
+            load_balancer::OKDLoadBalancerScore,
+        },
     },
     score::Score,
     topology::HAClusterTopology,
@@ -32,6 +35,7 @@ async fn main() {
     scores
         .append(&mut OKDInstallationPipeline::get_all_scores(HarmonyDiscoveryStrategy::MDNS).await);
 
+    scores.push(Box::new(OKDLoadBalancerScore::new(&topology)));
     harmony_cli::run(inventory, topology, scores, None)
         .await
         .unwrap();

examples/public_postgres/src/main.rs

@@ -15,7 +15,6 @@ async fn main() {
             ..Default::default() // Use harmony defaults, they are based on CNPG's default values :
                                  // 1 instance, 1Gi storage
         },
-        hostname: "postgrestest.sto1.nationtech.io".to_string(),
     };
 
     let test_connection = PostgreSQLConnectionScore {

examples/rhob_application_monitoring/src/main.rs

@@ -6,9 +6,9 @@ use harmony::{
         application::{
             ApplicationScore, RustWebFramework, RustWebapp, features::rhob_monitoring::Monitoring,
         },
-        monitoring::alert_channel::discord_alert_channel::DiscordReceiver,
+        monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
     },
-    topology::{K8sAnywhereTopology, monitoring::AlertRoute},
+    topology::K8sAnywhereTopology,
 };
 use harmony_types::{k8s_name::K8sName, net::Url};
 
@@ -22,21 +22,18 @@ async fn main() {
         service_port: 3000,
     });
 
-    let receiver_name = "test-discord".to_string();
-    let discord_receiver = DiscordReceiver {
-        name: receiver_name.clone(),
+    let discord_receiver = DiscordWebhook {
+        name: K8sName("test-discord".to_string()),
         url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
+        selectors: vec![],
     };
 
     let app = ApplicationScore {
         features: vec![
-            // Box::new(Monitoring {
-            //     application: application.clone(),
-            //     alert_receiver: vec![Box::new(discord_receiver)],
-            // }),
+            Box::new(Monitoring {
+                application: application.clone(),
+                alert_receiver: vec![Box::new(discord_receiver)],
+            }),
             // TODO add backups, multisite ha, etc
         ],
         application,

examples/rust/src/main.rs

@@ -8,13 +8,13 @@ use harmony::{
             features::{Monitoring, PackagingDeployment},
         },
         monitoring::alert_channel::{
-            discord_alert_channel::DiscordReceiver, webhook_receiver::WebhookReceiver,
+            discord_alert_channel::DiscordWebhook, webhook_receiver::WebhookReceiver,
         },
     },
-    topology::{K8sAnywhereTopology, monitoring::AlertRoute},
+    topology::K8sAnywhereTopology,
 };
 use harmony_macros::hurl;
-use harmony_types::{k8s_name::K8sName, net::Url};
+use harmony_types::k8s_name::K8sName;
 
 #[tokio::main]
 async fn main() {
@@ -26,23 +26,15 @@ async fn main() {
         service_port: 3000,
     });
 
-    let receiver_name = "test-discord".to_string();
-    let discord_receiver = DiscordReceiver {
-        name: receiver_name.clone(),
-        url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
+    let discord_receiver = DiscordWebhook {
+        name: K8sName("test-discord".to_string()),
+        url: hurl!("https://discord.doesnt.exist.com"),
+        selectors: vec![],
     };
 
-    let receiver_name = "sample-webhook-receiver".to_string();
-
     let webhook_receiver = WebhookReceiver {
-        name: receiver_name.clone(),
+        name: "sample-webhook-receiver".to_string(),
         url: hurl!("https://webhook-doesnt-exist.com"),
-        route: AlertRoute {
-            ..AlertRoute::default(receiver_name)
-        },
     };
 
     let app = ApplicationScore {
@@ -50,10 +42,10 @@ async fn main() {
             Box::new(PackagingDeployment {
                 application: application.clone(),
             }),
-            // Box::new(Monitoring {
-            //     application: application.clone(),
-            //     alert_receiver: vec![Box::new(discord_receiver), Box::new(webhook_receiver)],
-            // }),
+            Box::new(Monitoring {
+                application: application.clone(),
+                alert_receiver: vec![Box::new(discord_receiver), Box::new(webhook_receiver)],
+            }),
             // TODO add backups, multisite ha, etc
         ],
         application,

examples/try_rust_webapp/src/main.rs

@@ -1,8 +1,11 @@
 use harmony::{
     inventory::Inventory,
-    modules::application::{
-        ApplicationScore, RustWebFramework, RustWebapp,
-        features::{Monitoring, PackagingDeployment},
+    modules::{
+        application::{
+            ApplicationScore, RustWebFramework, RustWebapp,
+            features::{Monitoring, PackagingDeployment},
+        },
+        monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
     },
     topology::K8sAnywhereTopology,
 };
@@ -27,14 +30,14 @@ async fn main() {
             Box::new(PackagingDeployment {
                 application: application.clone(),
             }),
-            // Box::new(Monitoring {
-            //     application: application.clone(),
-            //     alert_receiver: vec![Box::new(DiscordWebhook {
-            //         name: K8sName("test-discord".to_string()),
-            //         url: hurl!("https://discord.doesnt.exist.com"),
-            //         selectors: vec![],
-            //     })],
-            // }),
+            Box::new(Monitoring {
+                application: application.clone(),
+                alert_receiver: vec![Box::new(DiscordWebhook {
+                    name: K8sName("test-discord".to_string()),
+                    url: hurl!("https://discord.doesnt.exist.com"),
+                    selectors: vec![],
+                })],
+            }),
         ],
         application,
     };

examples/tui/src/main.rs

@@ -44,6 +44,7 @@ fn build_large_score() -> LoadBalancerScore {
         ],
         listening_port: SocketAddr::V4(SocketAddrV4::new(ipv4!("192.168.0.0"), 49387)),
         health_check: Some(HealthCheck::HTTP(
+            Some(1993),
             "/some_long_ass_path_to_see_how_it_is_displayed_but_it_has_to_be_even_longer"
                 .to_string(),
             HttpMethod::GET,

harmony-k8s/src/resources.rs

@@ -2,13 +2,14 @@ use std::collections::HashMap;
 
 use k8s_openapi::api::{
     apps::v1::Deployment,
-    core::v1::{Node, ServiceAccount},
+    core::v1::{Namespace, Node, ServiceAccount},
 };
 use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
 use kube::api::ApiResource;
 use kube::{
     Error, Resource,
     api::{Api, DynamicObject, GroupVersionKind, ListParams, ObjectList},
+    core::ErrorResponse,
     runtime::conditions,
     runtime::wait::await_condition,
 };
@@ -313,4 +314,65 @@ impl K8sClient {
     ) -> Result<ObjectList<Node>, Error> {
         self.list_resources(None, list_params).await
     }
+
+    pub async fn namespace_exists(&self, name: &str) -> Result<bool, Error> {
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        match api.get_opt(name).await? {
+            Some(_) => Ok(true),
+            None => Ok(false),
+        }
+    }
+
+    pub async fn create_namespace(&self, name: &str) -> Result<Namespace, Error> {
+        let namespace = Namespace {
+            metadata: k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta {
+                name: Some(name.to_string()),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        api.create(&kube::api::PostParams::default(), &namespace)
+            .await
+    }
+
+    pub async fn wait_for_namespace(
+        &self,
+        name: &str,
+        timeout: Option<Duration>,
+    ) -> Result<(), Error> {
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        let timeout = timeout.unwrap_or(Duration::from_secs(60));
+        let start = std::time::Instant::now();
+
+        loop {
+            if start.elapsed() > timeout {
+                return Err(Error::Api(ErrorResponse {
+                    status: "Timeout".to_string(),
+                    message: format!("Namespace '{}' not ready within timeout", name),
+                    reason: "Timeout".to_string(),
+                    code: 408,
+                }));
+            }
+
+            match api.get_opt(name).await? {
+                Some(ns) => {
+                    if let Some(status) = ns.status {
+                        if status.phase == Some("Active".to_string()) {
+                            return Ok(());
+                        }
+                    }
+                }
+                None => {
+                    return Err(Error::Api(ErrorResponse {
+                        status: "NotFound".to_string(),
+                        message: format!("Namespace '{}' not found", name),
+                        reason: "NotFound".to_string(),
+                        code: 404,
+                    }));
+                }
+            }
+            tokio::time::sleep(Duration::from_millis(500)).await;
+        }
+    }
 }

harmony-k8s/src/types.rs

@@ -42,7 +42,7 @@ impl Default for DrainOptions {
         Self {
             delete_emptydir_data: false,
             ignore_daemonsets: true,
-            timeout: Duration::from_secs(1),
+            timeout: Duration::from_secs(120),
         }
     }
 }

harmony/src/domain/topology/k8s_anywhere/k8s_anywhere.rs

@@ -1,4 +1,4 @@
-use std::{collections::BTreeMap, process::Command, sync::Arc};
+use std::{collections::BTreeMap, process::Command, sync::Arc, time::Duration};
 
 use async_trait::async_trait;
 use base64::{Engine, engine::general_purpose};
@@ -8,7 +8,7 @@ use k8s_openapi::api::{
     core::v1::{Pod, Secret},
     rbac::v1::{ClusterRoleBinding, RoleRef, Subject},
 };
-use kube::api::{GroupVersionKind, ObjectMeta};
+use kube::api::{DynamicObject, GroupVersionKind, ObjectMeta};
 use log::{debug, info, trace, warn};
 use serde::Serialize;
 use tokio::sync::OnceCell;
@@ -29,7 +29,28 @@ use crate::{
             score_cert_management::CertificateManagementScore,
         },
         k3d::K3DInstallationScore,
+        k8s::ingress::{K8sIngressScore, PathType},
+        monitoring::{
+            grafana::{grafana::Grafana, helm::helm_grafana::grafana_helm_chart_score},
+            kube_prometheus::crd::{
+                crd_alertmanager_config::CRDPrometheus,
+                crd_grafana::{
+                    Grafana as GrafanaCRD, GrafanaCom, GrafanaDashboard,
+                    GrafanaDashboardDatasource, GrafanaDashboardSpec, GrafanaDatasource,
+                    GrafanaDatasourceConfig, GrafanaDatasourceJsonData,
+                    GrafanaDatasourceSecureJsonData, GrafanaDatasourceSpec, GrafanaSpec,
+                },
+                crd_prometheuses::LabelSelector,
+                prometheus_operator::prometheus_operator_helm_chart_score,
+                rhob_alertmanager_config::RHOBObservability,
+                service_monitor::ServiceMonitor,
+            },
+        },
         okd::{crd::ingresses_config::Ingress as IngressResource, route::OKDTlsPassthroughScore},
+        prometheus::{
+            k8s_prometheus_alerting_score::K8sPrometheusCRDAlertingScore,
+            prometheus::PrometheusMonitoring, rhob_alerting_score::RHOBAlertingScore,
+        },
     },
     score::Score,
     topology::{TlsRoute, TlsRouter, ingress::Ingress},
@@ -38,6 +59,7 @@ use crate::{
 use super::super::{
     DeploymentTarget, HelmCommand, K8sclient, MultiTargetTopology, PreparationError,
     PreparationOutcome, Topology,
+    oberservability::monitoring::AlertReceiver,
     tenant::{
         TenantConfig, TenantManager,
         k8s::K8sTenantManager,
@@ -87,6 +109,13 @@ impl K8sclient for K8sAnywhereTopology {
 
 #[async_trait]
 impl TlsRouter for K8sAnywhereTopology {
+    async fn get_public_domain(&self) -> Result<String, String> {
+        match &self.config.public_domain {
+            Some(public_domain) => Ok(public_domain.to_string()),
+            None => Err("Public domain not available".to_string()),
+        }
+    }
+
     async fn get_internal_domain(&self) -> Result<Option<String>, String> {
         match self.get_k8s_distribution().await.map_err(|e| {
             format!(
@@ -144,6 +173,216 @@ impl TlsRouter for K8sAnywhereTopology {
     }
 }
 
+#[async_trait]
+impl Grafana for K8sAnywhereTopology {
+    async fn ensure_grafana_operator(
+        &self,
+        inventory: &Inventory,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        debug!("ensure grafana operator");
+        let client = self.k8s_client().await.unwrap();
+        let grafana_gvk = GroupVersionKind {
+            group: "grafana.integreatly.org".to_string(),
+            version: "v1beta1".to_string(),
+            kind: "Grafana".to_string(),
+        };
+        let name = "grafanas.grafana.integreatly.org";
+        let ns = "grafana";
+
+        let grafana_crd = client
+            .get_resource_json_value(name, Some(ns), &grafana_gvk)
+            .await;
+        match grafana_crd {
+            Ok(_) => {
+                return Ok(PreparationOutcome::Success {
+                    details: "Found grafana CRDs in cluster".to_string(),
+                });
+            }
+
+            Err(_) => {
+                return self
+                    .install_grafana_operator(inventory, Some("grafana"))
+                    .await;
+            }
+        };
+    }
+    async fn install_grafana(&self) -> Result<PreparationOutcome, PreparationError> {
+        let ns = "grafana";
+
+        let mut label = BTreeMap::new();
+
+        label.insert("dashboards".to_string(), "grafana".to_string());
+
+        let label_selector = LabelSelector {
+            match_labels: label.clone(),
+            match_expressions: vec![],
+        };
+
+        let client = self.k8s_client().await?;
+
+        let grafana = self.build_grafana(ns, &label);
+
+        client.apply(&grafana, Some(ns)).await?;
+        //TODO change this to a ensure ready or something better than just a timeout
+        client
+            .wait_until_deployment_ready(
+                "grafana-grafana-deployment",
+                Some("grafana"),
+                Some(Duration::from_secs(30)),
+            )
+            .await?;
+
+        let sa_name = "grafana-grafana-sa";
+        let token_secret_name = "grafana-sa-token-secret";
+
+        let sa_token_secret = self.build_sa_token_secret(token_secret_name, sa_name, ns);
+
+        client.apply(&sa_token_secret, Some(ns)).await?;
+        let secret_gvk = GroupVersionKind {
+            group: "".to_string(),
+            version: "v1".to_string(),
+            kind: "Secret".to_string(),
+        };
+
+        let secret = client
+            .get_resource_json_value(token_secret_name, Some(ns), &secret_gvk)
+            .await?;
+
+        let token = format!(
+            "Bearer {}",
+            self.extract_and_normalize_token(&secret).unwrap()
+        );
+
+        debug!("creating grafana clusterrole binding");
+
+        let clusterrolebinding =
+            self.build_cluster_rolebinding(sa_name, "cluster-monitoring-view", ns);
+
+        client.apply(&clusterrolebinding, Some(ns)).await?;
+
+        debug!("creating grafana datasource crd");
+
+        let thanos_url = format!(
+            "https://{}",
+            self.get_domain("thanos-querier-openshift-monitoring")
+                .await
+                .unwrap()
+        );
+
+        let thanos_openshift_datasource = self.build_grafana_datasource(
+            "thanos-openshift-monitoring",
+            ns,
+            &label_selector,
+            &thanos_url,
+            &token,
+        );
+
+        client.apply(&thanos_openshift_datasource, Some(ns)).await?;
+
+        debug!("creating grafana dashboard crd");
+        let dashboard = self.build_grafana_dashboard(ns, &label_selector);
+
+        client.apply(&dashboard, Some(ns)).await?;
+        debug!("creating grafana ingress");
+        let grafana_ingress = self.build_grafana_ingress(ns).await;
+
+        grafana_ingress
+            .interpret(&Inventory::empty(), self)
+            .await
+            .map_err(|e| PreparationError::new(e.to_string()))?;
+
+        Ok(PreparationOutcome::Success {
+            details: "Installed grafana composants".to_string(),
+        })
+    }
+}
+
+#[async_trait]
+impl PrometheusMonitoring<CRDPrometheus> for K8sAnywhereTopology {
+    async fn install_prometheus(
+        &self,
+        sender: &CRDPrometheus,
+        _inventory: &Inventory,
+        _receivers: Option<Vec<Box<dyn AlertReceiver<CRDPrometheus>>>>,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let client = self.k8s_client().await?;
+
+        for monitor in sender.service_monitor.iter() {
+            client
+                .apply(monitor, Some(&sender.namespace))
+                .await
+                .map_err(|e| PreparationError::new(e.to_string()))?;
+        }
+        Ok(PreparationOutcome::Success {
+            details: "successfuly installed prometheus components".to_string(),
+        })
+    }
+
+    async fn ensure_prometheus_operator(
+        &self,
+        sender: &CRDPrometheus,
+        _inventory: &Inventory,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let po_result = self.ensure_prometheus_operator(sender).await?;
+
+        match po_result {
+            PreparationOutcome::Success { details: _ } => {
+                debug!("Detected prometheus crds operator present in cluster.");
+                return Ok(po_result);
+            }
+            PreparationOutcome::Noop => {
+                debug!("Skipping Prometheus CR installation due to missing operator.");
+                return Ok(po_result);
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl PrometheusMonitoring<RHOBObservability> for K8sAnywhereTopology {
+    async fn install_prometheus(
+        &self,
+        sender: &RHOBObservability,
+        inventory: &Inventory,
+        receivers: Option<Vec<Box<dyn AlertReceiver<RHOBObservability>>>>,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let po_result = self.ensure_cluster_observability_operator(sender).await?;
+
+        if po_result == PreparationOutcome::Noop {
+            debug!("Skipping Prometheus CR installation due to missing operator.");
+            return Ok(po_result);
+        }
+
+        let result = self
+            .get_cluster_observability_operator_prometheus_application_score(
+                sender.clone(),
+                receivers,
+            )
+            .await
+            .interpret(inventory, self)
+            .await;
+
+        match result {
+            Ok(outcome) => match outcome.status {
+                InterpretStatus::SUCCESS => Ok(PreparationOutcome::Success {
+                    details: outcome.message,
+                }),
+                InterpretStatus::NOOP => Ok(PreparationOutcome::Noop),
+                _ => Err(PreparationError::new(outcome.message)),
+            },
+            Err(err) => Err(PreparationError::new(err.to_string())),
+        }
+    }
+
+    async fn ensure_prometheus_operator(
+        &self,
+        sender: &RHOBObservability,
+        inventory: &Inventory,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        todo!()
+    }
+}
+
 impl Serialize for K8sAnywhereTopology {
     fn serialize<S>(&self, _serializer: S) -> Result<S::Ok, S::Error>
     where
@@ -348,6 +587,23 @@ impl K8sAnywhereTopology {
         }
     }
 
+    fn extract_and_normalize_token(&self, secret: &DynamicObject) -> Option<String> {
+        let token_b64 = secret
+            .data
+            .get("token")
+            .or_else(|| secret.data.get("data").and_then(|d| d.get("token")))
+            .and_then(|v| v.as_str())?;
+
+        let bytes = general_purpose::STANDARD.decode(token_b64).ok()?;
+
+        let s = String::from_utf8(bytes).ok()?;
+
+        let cleaned = s
+            .trim_matches(|c: char| c.is_whitespace() || c == '\0')
+            .to_string();
+        Some(cleaned)
+    }
+
     pub async fn get_k8s_distribution(&self) -> Result<KubernetesDistribution, PreparationError> {
         self.k8s_client()
             .await?
@@ -407,6 +663,141 @@ impl K8sAnywhereTopology {
         }
     }
 
+    fn build_grafana_datasource(
+        &self,
+        name: &str,
+        ns: &str,
+        label_selector: &LabelSelector,
+        url: &str,
+        token: &str,
+    ) -> GrafanaDatasource {
+        let mut json_data = BTreeMap::new();
+        json_data.insert("timeInterval".to_string(), "5s".to_string());
+
+        GrafanaDatasource {
+            metadata: ObjectMeta {
+                name: Some(name.to_string()),
+                namespace: Some(ns.to_string()),
+                ..Default::default()
+            },
+            spec: GrafanaDatasourceSpec {
+                instance_selector: label_selector.clone(),
+                allow_cross_namespace_import: Some(true),
+                values_from: None,
+                datasource: GrafanaDatasourceConfig {
+                    access: "proxy".to_string(),
+                    name: name.to_string(),
+                    r#type: "prometheus".to_string(),
+                    url: url.to_string(),
+                    database: None,
+                    json_data: Some(GrafanaDatasourceJsonData {
+                        time_interval: Some("60s".to_string()),
+                        http_header_name1: Some("Authorization".to_string()),
+                        tls_skip_verify: Some(true),
+                        oauth_pass_thru: Some(true),
+                    }),
+                    secure_json_data: Some(GrafanaDatasourceSecureJsonData {
+                        http_header_value1: Some(format!("Bearer {token}")),
+                    }),
+                    is_default: Some(false),
+                    editable: Some(true),
+                },
+            },
+        }
+    }
+
+    fn build_grafana_dashboard(
+        &self,
+        ns: &str,
+        label_selector: &LabelSelector,
+    ) -> GrafanaDashboard {
+        let graf_dashboard = GrafanaDashboard {
+            metadata: ObjectMeta {
+                name: Some(format!("grafana-dashboard-{}", ns)),
+                namespace: Some(ns.to_string()),
+                ..Default::default()
+            },
+            spec: GrafanaDashboardSpec {
+                resync_period: Some("30s".to_string()),
+                instance_selector: label_selector.clone(),
+                datasources: Some(vec![GrafanaDashboardDatasource {
+                    input_name: "DS_PROMETHEUS".to_string(),
+                    datasource_name: "thanos-openshift-monitoring".to_string(),
+                }]),
+                json: None,
+                grafana_com: Some(GrafanaCom {
+                    id: 17406,
+                    revision: None,
+                }),
+            },
+        };
+        graf_dashboard
+    }
+
+    fn build_grafana(&self, ns: &str, labels: &BTreeMap<String, String>) -> GrafanaCRD {
+        let grafana = GrafanaCRD {
+            metadata: ObjectMeta {
+                name: Some(format!("grafana-{}", ns)),
+                namespace: Some(ns.to_string()),
+                labels: Some(labels.clone()),
+                ..Default::default()
+            },
+            spec: GrafanaSpec {
+                config: None,
+                admin_user: None,
+                admin_password: None,
+                ingress: None,
+                persistence: None,
+                resources: None,
+            },
+        };
+        grafana
+    }
+
+    async fn build_grafana_ingress(&self, ns: &str) -> K8sIngressScore {
+        let domain = self.get_domain(&format!("grafana-{}", ns)).await.unwrap();
+        let name = format!("{}-grafana", ns);
+        let backend_service = format!("grafana-{}-service", ns);
+
+        K8sIngressScore {
+            name: fqdn::fqdn!(&name),
+            host: fqdn::fqdn!(&domain),
+            backend_service: fqdn::fqdn!(&backend_service),
+            port: 3000,
+            path: Some("/".to_string()),
+            path_type: Some(PathType::Prefix),
+            namespace: Some(fqdn::fqdn!(&ns)),
+            ingress_class_name: Some("openshift-default".to_string()),
+        }
+    }
+
+    async fn get_cluster_observability_operator_prometheus_application_score(
+        &self,
+        sender: RHOBObservability,
+        receivers: Option<Vec<Box<dyn AlertReceiver<RHOBObservability>>>>,
+    ) -> RHOBAlertingScore {
+        RHOBAlertingScore {
+            sender,
+            receivers: receivers.unwrap_or_default(),
+            service_monitors: vec![],
+            prometheus_rules: vec![],
+        }
+    }
+
+    async fn get_k8s_prometheus_application_score(
+        &self,
+        sender: CRDPrometheus,
+        receivers: Option<Vec<Box<dyn AlertReceiver<CRDPrometheus>>>>,
+        service_monitors: Option<Vec<ServiceMonitor>>,
+    ) -> K8sPrometheusCRDAlertingScore {
+        return K8sPrometheusCRDAlertingScore {
+            sender,
+            receivers: receivers.unwrap_or_default(),
+            service_monitors: service_monitors.unwrap_or_default(),
+            prometheus_rules: vec![],
+        };
+    }
+
     async fn openshift_ingress_operator_available(&self) -> Result<(), PreparationError> {
         let client = self.k8s_client().await?;
         let gvk = GroupVersionKind {
@@ -572,6 +963,137 @@ impl K8sAnywhereTopology {
             )),
         }
     }
+
+    async fn ensure_cluster_observability_operator(
+        &self,
+        sender: &RHOBObservability,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let status = Command::new("sh")
+            .args(["-c", "kubectl get crd -A | grep -i rhobs"])
+            .status()
+            .map_err(|e| PreparationError::new(format!("could not connect to cluster: {}", e)))?;
+
+        if !status.success() {
+            if let Some(Some(k8s_state)) = self.k8s_state.get() {
+                match k8s_state.source {
+                    K8sSource::LocalK3d => {
+                        warn!(
+                            "Installing observability operator is not supported on LocalK3d source"
+                        );
+                        return Ok(PreparationOutcome::Noop);
+                        debug!("installing cluster observability operator");
+                        todo!();
+                        let op_score =
+                            prometheus_operator_helm_chart_score(sender.namespace.clone());
+                        let result = op_score.interpret(&Inventory::empty(), self).await;
+
+                        return match result {
+                            Ok(outcome) => match outcome.status {
+                                InterpretStatus::SUCCESS => Ok(PreparationOutcome::Success {
+                                    details: "installed cluster observability operator".into(),
+                                }),
+                                InterpretStatus::NOOP => Ok(PreparationOutcome::Noop),
+                                _ => Err(PreparationError::new(
+                                    "failed to install cluster observability operator (unknown error)".into(),
+                                )),
+                            },
+                            Err(err) => Err(PreparationError::new(err.to_string())),
+                        };
+                    }
+                    K8sSource::Kubeconfig => {
+                        debug!(
+                            "unable to install cluster observability operator, contact cluster admin"
+                        );
+                        return Ok(PreparationOutcome::Noop);
+                    }
+                }
+            } else {
+                warn!(
+                    "Unable to detect k8s_state. Skipping Cluster Observability Operator install."
+                );
+                return Ok(PreparationOutcome::Noop);
+            }
+        }
+
+        debug!("Cluster Observability Operator is already present, skipping install");
+
+        Ok(PreparationOutcome::Success {
+            details: "cluster observability operator present in cluster".into(),
+        })
+    }
+
+    async fn ensure_prometheus_operator(
+        &self,
+        sender: &CRDPrometheus,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let status = Command::new("sh")
+            .args(["-c", "kubectl get crd -A | grep -i prometheuses"])
+            .status()
+            .map_err(|e| PreparationError::new(format!("could not connect to cluster: {}", e)))?;
+
+        if !status.success() {
+            if let Some(Some(k8s_state)) = self.k8s_state.get() {
+                match k8s_state.source {
+                    K8sSource::LocalK3d => {
+                        debug!("installing prometheus operator");
+                        let op_score =
+                            prometheus_operator_helm_chart_score(sender.namespace.clone());
+                        let result = op_score.interpret(&Inventory::empty(), self).await;
+
+                        return match result {
+                            Ok(outcome) => match outcome.status {
+                                InterpretStatus::SUCCESS => Ok(PreparationOutcome::Success {
+                                    details: "installed prometheus operator".into(),
+                                }),
+                                InterpretStatus::NOOP => Ok(PreparationOutcome::Noop),
+                                _ => Err(PreparationError::new(
+                                    "failed to install prometheus operator (unknown error)".into(),
+                                )),
+                            },
+                            Err(err) => Err(PreparationError::new(err.to_string())),
+                        };
+                    }
+                    K8sSource::Kubeconfig => {
+                        debug!("unable to install prometheus operator, contact cluster admin");
+                        return Ok(PreparationOutcome::Noop);
+                    }
+                }
+            } else {
+                warn!("Unable to detect k8s_state. Skipping Prometheus Operator install.");
+                return Ok(PreparationOutcome::Noop);
+            }
+        }
+
+        debug!("Prometheus operator is already present, skipping install");
+
+        Ok(PreparationOutcome::Success {
+            details: "prometheus operator present in cluster".into(),
+        })
+    }
+
+    async fn install_grafana_operator(
+        &self,
+        inventory: &Inventory,
+        ns: Option<&str>,
+    ) -> Result<PreparationOutcome, PreparationError> {
+        let namespace = ns.unwrap_or("grafana");
+        info!("installing grafana operator in ns {namespace}");
+        let tenant = self.get_k8s_tenant_manager()?.get_tenant_config().await;
+        let mut namespace_scope = false;
+        if tenant.is_some() {
+            namespace_scope = true;
+        }
+        let _grafana_operator_score = grafana_helm_chart_score(namespace, namespace_scope)
+            .interpret(inventory, self)
+            .await
+            .map_err(|e| PreparationError::new(e.to_string()));
+        Ok(PreparationOutcome::Success {
+            details: format!(
+                "Successfully installed grafana operator in ns {}",
+                ns.unwrap()
+            ),
+        })
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -609,6 +1131,7 @@ pub struct K8sAnywhereConfig {
     ///
     /// If the context name is not found, it will fail to initialize.
     pub k8s_context: Option<String>,
+    public_domain: Option<String>,
 }
 
 impl K8sAnywhereConfig {
@@ -636,6 +1159,7 @@ impl K8sAnywhereConfig {
 
         let mut kubeconfig: Option<String> = None;
         let mut k8s_context: Option<String> = None;
+        let mut public_domain: Option<String> = None;
 
         for part in env_var_value.split(',') {
             let kv: Vec<&str> = part.splitn(2, '=').collect();
@@ -643,6 +1167,7 @@ impl K8sAnywhereConfig {
                 match kv[0].trim() {
                     "kubeconfig" => kubeconfig = Some(kv[1].trim().to_string()),
                     "context" => k8s_context = Some(kv[1].trim().to_string()),
+                    "public_domain" => public_domain = Some(kv[1].trim().to_string()),
                     _ => {}
                 }
             }
@@ -660,6 +1185,7 @@ impl K8sAnywhereConfig {
         K8sAnywhereConfig {
             kubeconfig,
             k8s_context,
+            public_domain,
             use_system_kubeconfig,
             autoinstall: false,
             use_local_k3d: false,
@@ -702,6 +1228,7 @@ impl K8sAnywhereConfig {
             use_local_k3d: std::env::var("HARMONY_USE_LOCAL_K3D")
                 .map_or_else(|_| true, |v| v.parse().ok().unwrap_or(true)),
             k8s_context: std::env::var("HARMONY_K8S_CONTEXT").ok(),
+            public_domain: std::env::var("HARMONY_PUBLIC_DOMAIN").ok(),
         }
     }
 }

harmony/src/domain/topology/k8s_anywhere/mod.rs

@@ -1,5 +1,4 @@
 mod k8s_anywhere;
 pub mod nats;
-pub mod observability;
 mod postgres;
 pub use k8s_anywhere::*;

harmony/src/domain/topology/k8s_anywhere/observability/grafana.rs

@@ -1,147 +0,0 @@
-use async_trait::async_trait;
-
-use crate::{
-    inventory::Inventory,
-    modules::monitoring::grafana::{
-        grafana::Grafana,
-        k8s::{
-            score_ensure_grafana_ready::GrafanaK8sEnsureReadyScore,
-            score_grafana_alert_receiver::GrafanaK8sReceiverScore,
-            score_grafana_datasource::GrafanaK8sDatasourceScore,
-            score_grafana_rule::GrafanaK8sRuleScore, score_install_grafana::GrafanaK8sInstallScore,
-        },
-    },
-    score::Score,
-    topology::{
-        K8sAnywhereTopology, PreparationError, PreparationOutcome,
-        monitoring::{AlertReceiver, AlertRule, Observability, ScrapeTarget},
-    },
-};
-
-#[async_trait]
-impl Observability<Grafana> for K8sAnywhereTopology {
-    async fn install_alert_sender(
-        &self,
-        sender: &Grafana,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let score = GrafanaK8sInstallScore {
-            sender: sender.clone(),
-        };
-
-        score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(format!("Grafana not installed {}", e)))?;
-        Ok(PreparationOutcome::Success {
-            details: "Successfully installed grafana alert sender".to_string(),
-        })
-    }
-
-    async fn install_receivers(
-        &self,
-        sender: &Grafana,
-        inventory: &Inventory,
-        receivers: Option<Vec<Box<dyn AlertReceiver<Grafana>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let receivers = match receivers {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for receiver in receivers {
-            let score = GrafanaK8sReceiverScore {
-                receiver,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install receiver: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert receivers installed successfully".to_string(),
-        })
-    }
-
-    async fn install_rules(
-        &self,
-        sender: &Grafana,
-        inventory: &Inventory,
-        rules: Option<Vec<Box<dyn AlertRule<Grafana>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let rules = match rules {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for rule in rules {
-            let score = GrafanaK8sRuleScore {
-                sender: sender.clone(),
-                rule,
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install rule: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert rules installed successfully".to_string(),
-        })
-    }
-
-    async fn add_scrape_targets(
-        &self,
-        sender: &Grafana,
-        inventory: &Inventory,
-        scrape_targets: Option<Vec<Box<dyn ScrapeTarget<Grafana>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let scrape_targets = match scrape_targets {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for scrape_target in scrape_targets {
-            let score = GrafanaK8sDatasourceScore {
-                scrape_target,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to add DataSource: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All datasources installed successfully".to_string(),
-        })
-    }
-
-    async fn ensure_monitoring_installed(
-        &self,
-        sender: &Grafana,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let score = GrafanaK8sEnsureReadyScore {
-            sender: sender.clone(),
-        };
-
-        score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(format!("Grafana not ready {}", e)))?;
-        Ok(PreparationOutcome::Success {
-            details: "Grafana Ready".to_string(),
-        })
-    }
-}

harmony/src/domain/topology/k8s_anywhere/observability/kube_prometheus.rs

@@ -1,142 +0,0 @@
-use async_trait::async_trait;
-
-use crate::{
-    inventory::Inventory,
-    modules::monitoring::kube_prometheus::{
-        KubePrometheus, helm::kube_prometheus_helm_chart::kube_prometheus_helm_chart_score,
-        score_kube_prometheus_alert_receivers::KubePrometheusReceiverScore,
-        score_kube_prometheus_ensure_ready::KubePrometheusEnsureReadyScore,
-        score_kube_prometheus_rule::KubePrometheusRuleScore,
-        score_kube_prometheus_scrape_target::KubePrometheusScrapeTargetScore,
-    },
-    score::Score,
-    topology::{
-        K8sAnywhereTopology, PreparationError, PreparationOutcome,
-        monitoring::{AlertReceiver, AlertRule, Observability, ScrapeTarget},
-    },
-};
-
-#[async_trait]
-impl Observability<KubePrometheus> for K8sAnywhereTopology {
-    async fn install_alert_sender(
-        &self,
-        sender: &KubePrometheus,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        kube_prometheus_helm_chart_score(sender.config.clone())
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(e.to_string()))?;
-
-        Ok(PreparationOutcome::Success {
-            details: "Successfully installed kubeprometheus alert sender".to_string(),
-        })
-    }
-
-    async fn install_receivers(
-        &self,
-        sender: &KubePrometheus,
-        inventory: &Inventory,
-        receivers: Option<Vec<Box<dyn AlertReceiver<KubePrometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let receivers = match receivers {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for receiver in receivers {
-            let score = KubePrometheusReceiverScore {
-                receiver,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install receiver: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert receivers installed successfully".to_string(),
-        })
-    }
-
-    async fn install_rules(
-        &self,
-        sender: &KubePrometheus,
-        inventory: &Inventory,
-        rules: Option<Vec<Box<dyn AlertRule<KubePrometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let rules = match rules {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for rule in rules {
-            let score = KubePrometheusRuleScore {
-                sender: sender.clone(),
-                rule,
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install rule: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert rules installed successfully".to_string(),
-        })
-    }
-
-    async fn add_scrape_targets(
-        &self,
-        sender: &KubePrometheus,
-        inventory: &Inventory,
-        scrape_targets: Option<Vec<Box<dyn ScrapeTarget<KubePrometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let scrape_targets = match scrape_targets {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for scrape_target in scrape_targets {
-            let score = KubePrometheusScrapeTargetScore {
-                scrape_target,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install rule: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All scrap targets installed successfully".to_string(),
-        })
-    }
-
-    async fn ensure_monitoring_installed(
-        &self,
-        sender: &KubePrometheus,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let score = KubePrometheusEnsureReadyScore {
-            sender: sender.clone(),
-        };
-
-        score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(format!("KubePrometheus not ready {}", e)))?;
-        Ok(PreparationOutcome::Success {
-            details: "KubePrometheus Ready".to_string(),
-        })
-    }
-}

harmony/src/domain/topology/k8s_anywhere/observability/mod.rs

@@ -1,5 +0,0 @@
-pub mod grafana;
-pub mod kube_prometheus;
-pub mod openshift_monitoring;
-pub mod prometheus;
-pub mod redhat_cluster_observability;

harmony/src/domain/topology/k8s_anywhere/observability/openshift_monitoring.rs

@@ -1,142 +0,0 @@
-use async_trait::async_trait;
-use log::info;
-
-use crate::score::Score;
-use crate::{
-    inventory::Inventory,
-    modules::monitoring::okd::{
-        OpenshiftClusterAlertSender,
-        score_enable_cluster_monitoring::OpenshiftEnableClusterMonitoringScore,
-        score_openshift_alert_rule::OpenshiftAlertRuleScore,
-        score_openshift_receiver::OpenshiftReceiverScore,
-        score_openshift_scrape_target::OpenshiftScrapeTargetScore,
-        score_user_workload::OpenshiftUserWorkloadMonitoring,
-        score_verify_user_workload_monitoring::VerifyUserWorkload,
-    },
-    topology::{
-        K8sAnywhereTopology, PreparationError, PreparationOutcome,
-        monitoring::{AlertReceiver, AlertRule, Observability, ScrapeTarget},
-    },
-};
-
-#[async_trait]
-impl Observability<OpenshiftClusterAlertSender> for K8sAnywhereTopology {
-    async fn install_alert_sender(
-        &self,
-        _sender: &OpenshiftClusterAlertSender,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        info!("enabling cluster monitoring");
-        let cluster_monitoring_score = OpenshiftEnableClusterMonitoringScore {};
-        cluster_monitoring_score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError { msg: e.to_string() })?;
-
-        info!("enabling user workload monitoring");
-        let user_workload_score = OpenshiftUserWorkloadMonitoring {};
-        user_workload_score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError { msg: e.to_string() })?;
-
-        Ok(PreparationOutcome::Success {
-            details: "Successfully configured cluster monitoring".to_string(),
-        })
-    }
-
-    async fn install_receivers(
-        &self,
-        _sender: &OpenshiftClusterAlertSender,
-        inventory: &Inventory,
-        receivers: Option<Vec<Box<dyn AlertReceiver<OpenshiftClusterAlertSender>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        if let Some(receivers) = receivers {
-            for receiver in receivers {
-                info!("Installing receiver {}", receiver.name());
-                let receiver_score = OpenshiftReceiverScore { receiver };
-                receiver_score
-                    .create_interpret()
-                    .execute(inventory, self)
-                    .await
-                    .map_err(|e| PreparationError { msg: e.to_string() })?;
-            }
-            Ok(PreparationOutcome::Success {
-                details: "Successfully installed receivers for OpenshiftClusterMonitoring"
-                    .to_string(),
-            })
-        } else {
-            Ok(PreparationOutcome::Noop)
-        }
-    }
-
-    async fn install_rules(
-        &self,
-        _sender: &OpenshiftClusterAlertSender,
-        inventory: &Inventory,
-        rules: Option<Vec<Box<dyn AlertRule<OpenshiftClusterAlertSender>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        if let Some(rules) = rules {
-            for rule in rules {
-                info!("Installing rule ");
-                let rule_score = OpenshiftAlertRuleScore { rule: rule };
-                rule_score
-                    .create_interpret()
-                    .execute(inventory, self)
-                    .await
-                    .map_err(|e| PreparationError { msg: e.to_string() })?;
-            }
-            Ok(PreparationOutcome::Success {
-                details: "Successfully installed rules for OpenshiftClusterMonitoring".to_string(),
-            })
-        } else {
-            Ok(PreparationOutcome::Noop)
-        }
-    }
-
-    async fn add_scrape_targets(
-        &self,
-        _sender: &OpenshiftClusterAlertSender,
-        inventory: &Inventory,
-        scrape_targets: Option<Vec<Box<dyn ScrapeTarget<OpenshiftClusterAlertSender>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        if let Some(scrape_targets) = scrape_targets {
-            for scrape_target in scrape_targets {
-                info!("Installing scrape target");
-                let scrape_target_score = OpenshiftScrapeTargetScore {
-                    scrape_target: scrape_target,
-                };
-                scrape_target_score
-                    .create_interpret()
-                    .execute(inventory, self)
-                    .await
-                    .map_err(|e| PreparationError { msg: e.to_string() })?;
-            }
-            Ok(PreparationOutcome::Success {
-                details: "Successfully added scrape targets for OpenshiftClusterMonitoring"
-                    .to_string(),
-            })
-        } else {
-            Ok(PreparationOutcome::Noop)
-        }
-    }
-
-    async fn ensure_monitoring_installed(
-        &self,
-        _sender: &OpenshiftClusterAlertSender,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let verify_monitoring_score = VerifyUserWorkload {};
-        info!("Verifying user workload and cluster monitoring installed");
-        verify_monitoring_score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError { msg: e.to_string() })?;
-        Ok(PreparationOutcome::Success {
-            details: "OpenshiftClusterMonitoring ready".to_string(),
-        })
-    }
-}

harmony/src/domain/topology/k8s_anywhere/observability/prometheus.rs

@@ -1,147 +0,0 @@
-use async_trait::async_trait;
-
-use crate::{
-    inventory::Inventory,
-    modules::monitoring::prometheus::{
-        Prometheus, score_prometheus_alert_receivers::PrometheusReceiverScore,
-        score_prometheus_ensure_ready::PrometheusEnsureReadyScore,
-        score_prometheus_install::PrometheusInstallScore,
-        score_prometheus_rule::PrometheusRuleScore,
-        score_prometheus_scrape_target::PrometheusScrapeTargetScore,
-    },
-    score::Score,
-    topology::{
-        K8sAnywhereTopology, PreparationError, PreparationOutcome,
-        monitoring::{AlertReceiver, AlertRule, Observability, ScrapeTarget},
-    },
-};
-
-#[async_trait]
-impl Observability<Prometheus> for K8sAnywhereTopology {
-    async fn install_alert_sender(
-        &self,
-        sender: &Prometheus,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let score = PrometheusInstallScore {
-            sender: sender.clone(),
-        };
-
-        score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(format!("Prometheus not installed {}", e)))?;
-
-        Ok(PreparationOutcome::Success {
-            details: "Successfully installed kubeprometheus alert sender".to_string(),
-        })
-    }
-
-    async fn install_receivers(
-        &self,
-        sender: &Prometheus,
-        inventory: &Inventory,
-        receivers: Option<Vec<Box<dyn AlertReceiver<Prometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let receivers = match receivers {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for receiver in receivers {
-            let score = PrometheusReceiverScore {
-                receiver,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install receiver: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert receivers installed successfully".to_string(),
-        })
-    }
-
-    async fn install_rules(
-        &self,
-        sender: &Prometheus,
-        inventory: &Inventory,
-        rules: Option<Vec<Box<dyn AlertRule<Prometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let rules = match rules {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for rule in rules {
-            let score = PrometheusRuleScore {
-                sender: sender.clone(),
-                rule,
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install rule: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All alert rules installed successfully".to_string(),
-        })
-    }
-
-    async fn add_scrape_targets(
-        &self,
-        sender: &Prometheus,
-        inventory: &Inventory,
-        scrape_targets: Option<Vec<Box<dyn ScrapeTarget<Prometheus>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let scrape_targets = match scrape_targets {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for scrape_target in scrape_targets {
-            let score = PrometheusScrapeTargetScore {
-                scrape_target,
-                sender: sender.clone(),
-            };
-
-            score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(format!("Failed to install rule: {}", e)))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "All scrap targets installed successfully".to_string(),
-        })
-    }
-
-    async fn ensure_monitoring_installed(
-        &self,
-        sender: &Prometheus,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let score = PrometheusEnsureReadyScore {
-            sender: sender.clone(),
-        };
-
-        score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(format!("Prometheus not ready {}", e)))?;
-
-        Ok(PreparationOutcome::Success {
-            details: "Prometheus Ready".to_string(),
-        })
-    }
-}

harmony/src/domain/topology/k8s_anywhere/observability/redhat_cluster_observability.rs

@@ -1,116 +0,0 @@
-use crate::{
-    modules::monitoring::red_hat_cluster_observability::{
-        score_alert_receiver::RedHatClusterObservabilityReceiverScore,
-        score_coo_monitoring_stack::RedHatClusterObservabilityMonitoringStackScore,
-    },
-    score::Score,
-};
-use async_trait::async_trait;
-use log::info;
-
-use crate::{
-    inventory::Inventory,
-    modules::monitoring::red_hat_cluster_observability::{
-        RedHatClusterObservability,
-        score_redhat_cluster_observability_operator::RedHatClusterObservabilityOperatorScore,
-    },
-    topology::{
-        K8sAnywhereTopology, PreparationError, PreparationOutcome,
-        monitoring::{AlertReceiver, AlertRule, Observability, ScrapeTarget},
-    },
-};
-
-#[async_trait]
-impl Observability<RedHatClusterObservability> for K8sAnywhereTopology {
-    async fn install_alert_sender(
-        &self,
-        sender: &RedHatClusterObservability,
-        inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        info!("Verifying Redhat Cluster Observability Operator");
-
-        let coo_score = RedHatClusterObservabilityOperatorScore::default();
-
-        coo_score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(e.to_string()))?;
-
-        info!(
-            "Installing Cluster Observability Operator Monitoring Stack in ns {}",
-            sender.namespace.clone()
-        );
-
-        let coo_monitoring_stack_score = RedHatClusterObservabilityMonitoringStackScore {
-            namespace: sender.namespace.clone(),
-            resource_selector: sender.resource_selector.clone(),
-        };
-
-        coo_monitoring_stack_score
-            .create_interpret()
-            .execute(inventory, self)
-            .await
-            .map_err(|e| PreparationError::new(e.to_string()))?;
-
-        Ok(PreparationOutcome::Success {
-            details: "Successfully installed RedHatClusterObservability Operator".to_string(),
-        })
-    }
-
-    async fn install_receivers(
-        &self,
-        sender: &RedHatClusterObservability,
-        inventory: &Inventory,
-        receivers: Option<Vec<Box<dyn AlertReceiver<RedHatClusterObservability>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        let receivers = match receivers {
-            Some(r) if !r.is_empty() => r,
-            _ => return Ok(PreparationOutcome::Noop),
-        };
-
-        for receiver in receivers {
-            info!("Installing receiver {}", receiver.name());
-
-            let receiver_score = RedHatClusterObservabilityReceiverScore {
-                receiver,
-                sender: sender.clone(),
-            };
-            receiver_score
-                .create_interpret()
-                .execute(inventory, self)
-                .await
-                .map_err(|e| PreparationError::new(e.to_string()))?;
-        }
-
-        Ok(PreparationOutcome::Success {
-            details: "Successfully installed receivers for OpenshiftClusterMonitoring".to_string(),
-        })
-    }
-
-    async fn install_rules(
-        &self,
-        _sender: &RedHatClusterObservability,
-        _inventory: &Inventory,
-        _rules: Option<Vec<Box<dyn AlertRule<RedHatClusterObservability>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        todo!()
-    }
-
-    async fn add_scrape_targets(
-        &self,
-        _sender: &RedHatClusterObservability,
-        _inventory: &Inventory,
-        _scrape_targets: Option<Vec<Box<dyn ScrapeTarget<RedHatClusterObservability>>>>,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        todo!()
-    }
-
-    async fn ensure_monitoring_installed(
-        &self,
-        _sender: &RedHatClusterObservability,
-        _inventory: &Inventory,
-    ) -> Result<PreparationOutcome, PreparationError> {
-        todo!()
-    }
-}

harmony/src/domain/topology/load_balancer.rs

@@ -106,6 +106,7 @@ pub enum SSL {
 
 #[derive(Debug, Clone, PartialEq, Serialize)]
 pub enum HealthCheck {
-    HTTP(String, HttpMethod, HttpStatusCode, SSL),
+    /// HTTP(None, "/healthz/ready", HttpMethod::GET, HttpStatusCode::Success2xx, SSL::Disabled)
+    HTTP(Option<u16>, String, HttpMethod, HttpStatusCode, SSL),
     TCP(Option<u16>),
 }

harmony/src/domain/topology/mod.rs

@@ -2,7 +2,6 @@ pub mod decentralized;
 mod failover;
 mod ha_cluster;
 pub mod ingress;
-pub mod monitoring;
 pub mod node_exporter;
 pub mod opnsense;
 pub use failover::*;
@@ -12,6 +11,7 @@ mod http;
 pub mod installable;
 mod k8s_anywhere;
 mod localhost;
+pub mod oberservability;
 pub mod tenant;
 use derive_new::new;
 pub use k8s_anywhere::*;