doc: Initial documentation for the MultisitePostgreSQL module

Also alias `port` to support both `port` and `ports` as per the nmstate spec.

Reviewed-on: #186

brocade/src/fast_iron.rs

@@ -1,8 +1,7 @@
 use super::BrocadeClient;
 use crate::{
     BrocadeInfo, Error, ExecutionMode, InterSwitchLink, InterfaceInfo, MacAddressEntry,
-    PortChannelId, PortOperatingMode, SecurityLevel, parse_brocade_mac_address,
-    shell::BrocadeShell,
+    PortChannelId, PortOperatingMode, parse_brocade_mac_address, shell::BrocadeShell,
 };
 
 use async_trait::async_trait;
@@ -210,20 +209,4 @@ impl BrocadeClient for FastIronClient {
         info!("[Brocade] Port-channel '{channel_name}' cleared.");
         Ok(())
     }
-
-    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error> {
-        let commands = vec![
-            "configure terminal".into(),
-            "snmp-server view ALL 1 included".into(),
-            "snmp-server group public v3 priv read ALL".into(),
-            format!(
-                "snmp-server user {user_name} groupname public auth md5 auth-password {auth} priv des priv-password {des}"
-            ),
-            "exit".into(),
-        ];
-        self.shell
-            .run_commands(commands, ExecutionMode::Regular)
-            .await?;
-        Ok(())
-    }
 }

brocade/src/lib.rs

@@ -237,15 +237,6 @@ pub trait BrocadeClient: std::fmt::Debug {
         ports: &[PortLocation],
     ) -> Result<(), Error>;
 
-    /// Enables Simple Network Management Protocol (SNMP) server for switch
-    ///
-    /// # Parameters
-    ///
-    ///  * `user_name`: The user name for the snmp server
-    ///  * `auth`: The password for authentication process for verifying the identity of a device
-    ///  * `des`: The Data Encryption Standard algorithm key
-    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error>;
-
     /// Removes all configuration associated with the specified Port-Channel name.
     ///
     /// This operation should be idempotent; attempting to clear a non-existent
@@ -309,11 +300,6 @@ fn parse_brocade_mac_address(value: &str) -> Result<MacAddress, String> {
     Ok(MacAddress(bytes))
 }
 
-#[derive(Debug)]
-pub enum SecurityLevel {
-    AuthPriv(String),
-}
-
 #[derive(Debug)]
 pub enum Error {
     NetworkError(String),

brocade/src/network_operating_system.rs

@@ -8,7 +8,7 @@ use regex::Regex;
 use crate::{
     BrocadeClient, BrocadeInfo, Error, ExecutionMode, InterSwitchLink, InterfaceInfo,
     InterfaceStatus, InterfaceType, MacAddressEntry, PortChannelId, PortOperatingMode,
-    SecurityLevel, parse_brocade_mac_address, shell::BrocadeShell,
+    parse_brocade_mac_address, shell::BrocadeShell,
 };
 
 #[derive(Debug)]
@@ -330,20 +330,4 @@ impl BrocadeClient for NetworkOperatingSystemClient {
         info!("[Brocade] Port-channel '{channel_name}' cleared.");
         Ok(())
     }
-
-    async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error> {
-        let commands = vec![
-            "configure terminal".into(),
-            "snmp-server view ALL 1 included".into(),
-            "snmp-server group public v3 priv read ALL".into(),
-            format!(
-                "snmp-server user {user_name} groupname public auth md5 auth-password {auth} priv des priv-password {des}"
-            ),
-            "exit".into(),
-        ];
-        self.shell
-            .run_commands(commands, ExecutionMode::Regular)
-            .await?;
-        Ok(())
-    }
 }

docs/modules/Multisite_PostgreSQL.md

@@ -0,0 +1,105 @@
+# Design Document: Harmony PostgreSQL Module
+
+**Status:** Draft
+**Last Updated:** 2023-10-27
+**Context:** Multi-site Data Replication & Orchestration
+
+## 1. Overview
+
+The Harmony PostgreSQL Module provides a high-level abstraction for deploying and managing high-availability PostgreSQL clusters across geographically distributed Kubernetes/OKD sites.
+
+Instead of manually configuring complex replication slots, firewalls, and operator settings on each cluster, users define a single intent (a **Score**), and Harmony orchestrates the underlying infrastructure (the **Arrangement**) to establish a Primary-Replica architecture.
+
+Currently, the implementation relies on the **CloudNativePG (CNPG)** operator as the backing engine.
+
+## 2. Architecture
+
+### 2.1 The Abstraction Model
+Following **ADR 003 (Infrastructure Abstraction)**, Harmony separates the *intent* from the *implementation*.
+
+1.  **The Score (Intent):** The user defines a `MultisitePostgreSQL` resource. This describes *what* is needed (e.g., "A Postgres 15 cluster with 10GB storage, Primary on Site A, Replica on Site B").
+2.  **The Interpret (Action):** Harmony MultisitePostgreSQLInterpret processes this Score and orchestrates the deployment on both sites to reach the state defined in the Score.
+3.  **The Capability (Implementation):** The PostgreSQL Capability is implemented by the K8sTopology and the interpret can deploy it, configure it and fetch information about it. The concrete implementation will rely on the mature CloudnativePG operator to manage all the Kubernetes resources required.
+
+### 2.2 Network Connectivity (TLS Passthrough)
+
+One of the critical challenges in multi-site orchestration is secure connectivity between clusters that may have dynamic IPs or strict firewalls.
+
+To solve this, we utilize **OKD/OpenShift Routes with TLS Passthrough**.
+
+*   **Mechanism:** The Primary site exposes a `Route` configured for `termination: passthrough`.
+*   **Routing:** The OpenShift HAProxy router inspects the **SNI (Server Name Indication)** header of the incoming TCP connection to route traffic to the correct PostgreSQL Pod.
+*   **Security:** SSL is **not** terminated at the ingress router. The encrypted stream is passed directly to the PostgreSQL instance. Mutual TLS (mTLS) authentication is handled natively by CNPG between the Primary and Replica instances.
+*   **Dynamic IPs:** Because connections are established via DNS hostnames (the Route URL), this architecture is resilient to dynamic IP changes at the Primary site.
+
+#### Traffic Flow Diagram
+
+```text
+[ Site B: Replica ]                 [ Site A: Primary ]
+      |                                     |
+(CNPG Instance) --[Encrypted TCP]--> (OKD HAProxy Router)
+      |           (Port 443)                |
+      |                                     |
+      |                            [SNI Inspection]
+      |                                     |
+      |                                     v
+      |                            (PostgreSQL Primary Pod)
+      |                                   (Port 5432)
+```
+
+## 3. Design Decisions
+
+### Why CloudNativePG?
+We selected CloudNativePG because it relies exclusively on standard Kubernetes primitives and uses the native PostgreSQL replication protocol (WAL shipping/Streaming). This aligns with Harmony's goal of being "K8s Native."
+
+### Why TLS Passthrough instead of VPN/NodePort?
+*   **NodePort:** Requires static IPs and opening non-standard ports on the firewall, which violates our security constraints.
+*   **VPN (e.g., Wireguard/Tailscale):** While secure, it introduces significant complexity (sidecars, key management) and external dependencies.
+*   **TLS Passthrough:** Leverages the existing Ingress/Router infrastructure already present in OKD. It requires zero additional software and respects multi-tenancy (Routes are namespaced).
+
+### Configuration Philosophy (YAGNI)
+The current design exposes a **generic configuration surface**. Users can configure standard parameters (Storage size, CPU/Memory requests, Postgres version).
+
+**We explicitly do not expose advanced CNPG or PostgreSQL configurations at this stage.**
+
+*   **Reasoning:** We aim to keep the API surface small and manageable.
+*   **Future Path:** We plan to implement a "pass-through" mechanism to allow sending raw config maps or custom parameters to the underlying engine (CNPG) *only when a concrete use case arises*. Until then, we adhere to the **YAGNI (You Ain't Gonna Need It)** principle to avoid premature optimization and API bloat.
+
+## 4. Usage Guide
+
+To deploy a multi-site cluster, apply the `MultisitePostgreSQL` resource to the Harmony Control Plane.
+
+### Example Manifest
+
+```yaml
+apiVersion: harmony.io/v1alpha1
+kind: MultisitePostgreSQL
+metadata:
+  name: finance-db
+  namespace: tenant-a
+spec:
+  version: "15"
+  storage: "10Gi"
+  resources:
+    requests:
+      cpu: "500m"
+      memory: "1Gi"
+  
+  # Topology Definition
+  topology:
+    primary:
+      site: "site-paris" # The name of the cluster in Harmony
+    replicas:
+      - site: "site-newyork"
+```
+
+### What happens next?
+1.  Harmony detects the CR.
+2.  **On Site Paris:** It deploys a CNPG Cluster (Primary) and creates a Passthrough Route `postgres-finance-db.apps.site-paris.example.com`.
+3.  **On Site New York:** It deploys a CNPG Cluster (Replica) configured with `externalClusters` pointing to the Paris Route.
+4.  Data begins replicating immediately over the encrypted channel.
+
+## 5. Troubleshooting
+
+*   **Connection Refused:** Ensure the Primary site's Route is successfully admitted by the Ingress Controller.
+*   **Certificate Errors:** CNPG manages mTLS automatically. If errors persist, ensure the CA secrets were correctly propagated by Harmony from Primary to Replica namespaces.

examples/brocade_snmp_server/Cargo.toml

@@ -1,20 +0,0 @@
-[package]
-name = "brocade-snmp-server"
-edition = "2024"
-version.workspace = true
-readme.workspace = true
-license.workspace = true
-
-[dependencies]
-harmony = { path = "../../harmony" }
-brocade = { path = "../../brocade" }
-harmony_secret = { path = "../../harmony_secret" }
-harmony_cli = { path = "../../harmony_cli" }
-harmony_types = { path = "../../harmony_types" }
-harmony_macros = { path = "../../harmony_macros" }
-tokio = { workspace = true }
-log = { workspace = true }
-env_logger = { workspace = true }
-url = { workspace = true }
-base64.workspace = true
-serde.workspace = true

examples/brocade_snmp_server/src/main.rs

@@ -1,22 +0,0 @@
-use std::net::{IpAddr, Ipv4Addr};
-
-use harmony::{
-    inventory::Inventory, modules::brocade::BrocadeEnableSnmpScore, topology::K8sAnywhereTopology,
-};
-
-#[tokio::main]
-async fn main() {
-    let brocade_snmp_server = BrocadeEnableSnmpScore {
-        server_ips: vec![IpAddr::V4(Ipv4Addr::new(192, 168, 1, 111))],
-        dry_run: true,
-    };
-
-    harmony_cli::run(
-        Inventory::autoload(),
-        K8sAnywhereTopology::from_env(),
-        vec![Box::new(brocade_snmp_server)],
-        None,
-    )
-    .await
-    .unwrap();
-}

harmony/src/infra/brocade.rs

@@ -121,7 +121,7 @@ mod tests {
     use async_trait::async_trait;
     use brocade::{
         BrocadeClient, BrocadeInfo, Error, InterSwitchLink, InterfaceInfo, InterfaceStatus,
-        InterfaceType, MacAddressEntry, PortChannelId, PortOperatingMode, SecurityLevel,
+        InterfaceType, MacAddressEntry, PortChannelId, PortOperatingMode,
     };
     use harmony_types::switch::PortLocation;
 
@@ -279,10 +279,6 @@ mod tests {
         async fn clear_port_channel(&self, _channel_name: &str) -> Result<(), Error> {
             todo!()
         }
-
-        async fn enable_snmp(&self, user_name: &str, auth: &str, des: &str) -> Result<(), Error> {
-            todo!()
-        }
     }
 
     impl FakeBrocadeClient {

harmony/src/infra/network_manager.rs

@@ -135,8 +135,6 @@ impl OpenShiftNmStateNetworkManager {
                 description: Some(format!("Member of bond {bond_name}")),
                 r#type: nmstate::InterfaceType::Ethernet,
                 state: "up".to_string(),
-                mtu: Some(switch_port.interface.mtu),
-                mac_address: Some(switch_port.interface.mac_address.to_string()),
                 ipv4: Some(nmstate::IpStackSpec {
                     enabled: Some(false),
                     ..Default::default()
@@ -162,7 +160,7 @@ impl OpenShiftNmStateNetworkManager {
 
         interfaces.push(nmstate::Interface {
             name: bond_name.to_string(),
-            description: Some(format!("Network bond for host {host}")),
+            description: Some(format!("HARMONY - Network bond for host {host}")),
             r#type: nmstate::InterfaceType::Bond,
             state: "up".to_string(),
             copy_mac_from,

harmony/src/modules/brocade.rs

@@ -1,117 +0,0 @@
-use std::net::{IpAddr, Ipv4Addr};
-
-use async_trait::async_trait;
-use brocade::BrocadeOptions;
-use harmony_secret::{Secret, SecretManager};
-use harmony_types::id::Id;
-use serde::{Deserialize, Serialize};
-
-use crate::{
-    data::Version,
-    interpret::{Interpret, InterpretError, InterpretName, InterpretStatus, Outcome},
-    inventory::Inventory,
-    score::Score,
-    topology::Topology,
-};
-
-#[derive(Debug, Clone, Serialize)]
-pub struct BrocadeEnableSnmpScore {
-    pub server_ips: Vec<IpAddr>,
-    pub dry_run: bool,
-}
-
-impl<T: Topology> Score<T> for BrocadeEnableSnmpScore {
-    fn name(&self) -> String {
-        "BrocadeEnableSnmpScore".to_string()
-    }
-
-    fn create_interpret(&self) -> Box<dyn Interpret<T>> {
-        Box::new(BrocadeEnableSnmpInterpret {
-            score: self.clone(),
-        })
-    }
-}
-
-#[derive(Debug, Clone, Serialize)]
-pub struct BrocadeEnableSnmpInterpret {
-    score: BrocadeEnableSnmpScore,
-}
-
-#[derive(Secret, Clone, Debug, Serialize, Deserialize)]
-struct BrocadeSwitchAuth {
-    username: String,
-    password: String,
-}
-
-#[derive(Secret, Clone, Debug, Serialize, Deserialize)]
-struct BrocadeSnmpAuth {
-    username: String,
-    auth_password: String,
-    des_password: String,
-}
-
-#[async_trait]
-impl<T: Topology> Interpret<T> for BrocadeEnableSnmpInterpret {
-    async fn execute(
-        &self,
-        _inventory: &Inventory,
-        _topology: &T,
-    ) -> Result<Outcome, InterpretError> {
-        let switch_addresses = &self.score.server_ips;
-
-        let snmp_auth = SecretManager::get_or_prompt::<BrocadeSnmpAuth>()
-            .await
-            .unwrap();
-
-        let config = SecretManager::get_or_prompt::<BrocadeSwitchAuth>()
-            .await
-            .unwrap();
-
-        let brocade = brocade::init(
-            &switch_addresses,
-            22,
-            &config.username,
-            &config.password,
-            Some(BrocadeOptions {
-                dry_run: self.score.dry_run,
-                ..Default::default()
-            }),
-        )
-        .await
-        .expect("Brocade client failed to connect");
-
-        brocade
-            .enable_snmp(
-                &snmp_auth.username,
-                &snmp_auth.auth_password,
-                &snmp_auth.des_password,
-            )
-            .await
-            .map_err(|e| InterpretError::new(e.to_string()))?;
-
-        Ok(Outcome::success(format!(
-            "Activated snmp server for Brocade at {}",
-            switch_addresses
-                .iter()
-                .map(|s| s.to_string())
-                .collect::<Vec<_>>()
-                .join(", ")
-        )))
-    }
-
-    fn get_name(&self) -> InterpretName {
-        InterpretName::Custom("BrocadeEnableSnmpInterpret")
-    }
-
-    fn get_version(&self) -> Version {
-        todo!()
-    }
-
-    fn get_status(&self) -> InterpretStatus {
-        todo!()
-    }
-
-    fn get_children(&self) -> Vec<Id> {
-        todo!()
-    }
-}

harmony/src/modules/mod.rs

@@ -1,5 +1,4 @@
 pub mod application;
-pub mod brocade;
 pub mod cert_manager;
 pub mod dhcp;
 pub mod dns;

harmony/src/modules/okd/crd/nmstate.rs

@@ -417,6 +417,7 @@ pub struct EthernetSpec {
 #[serde(rename_all = "kebab-case")]
 pub struct BondSpec {
     pub mode: String,
+    #[serde(alias = "port")]
     pub ports: Vec<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub options: Option<BTreeMap<String, Value>>,

harmony_types/src/net.rs

@@ -1,6 +1,6 @@
 use serde::{Deserialize, Serialize};
 
-#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
+#[derive(Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
 pub struct MacAddress(pub [u8; 6]);
 
 impl MacAddress {
@@ -19,6 +19,14 @@ impl From<&MacAddress> for String {
     }
 }
 
+impl std::fmt::Debug for MacAddress {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple("MacAddress")
+            .field(&String::from(self))
+            .finish()
+    }
+}
+
 impl std::fmt::Display for MacAddress {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.write_str(&String::from(self))