doc(okdinstallationscore): Fix incorrect comments and remove some more useless comments

harmony/src/modules/okd/installation.rs

@@ -2,39 +2,29 @@
 //!
 //! Overview
 //! --------
-//! OKDInstallationScore orchestrates an end-to-end, bare-metal OKD (OpenShift/OKD 4.19)
+//! OKDInstallationScore orchestrates an end-to-end, bare-metal OKD (OpenShift/OKD 4.19).
-//! installation using Harmony’s strongly-typed Scores and Interprets. It encodes the
+//! It follows principles of “discovery-first, then provision” strategy with strict ordering,
-//! “discovery-first, then provision” strategy with strict ordering, observable progress,
+//! observable progress, and minimal assumptions about the underlying network.
-//! and minimal assumptions about the underlying network.
-//!
-//! Design goals
-//! - Deterministic, observable pipeline from unknown hardware to a healthy OKD cluster.
-//! - Do NOT require LACP bonding during PXE/inventory. Bonding is configured only
-//!   after the host has a stable OS on disk (SCOS/RHCOS) and OKD MachineConfigs/NNCP
-//!   can enforce persistence safely.
-//! - Support per-MAC iPXE rendering without requiring multiple DHCP reservations for
-//!   the same host. Discovery runs with generic DHCP (access/unbonded). Role-specific
-//!   per-MAC PXE entries are activated just-in-time before install.
-//! - Emit HarmonyEvent instrumentation at each step via the Score::interpret path.
 //!
 //! High-level flow
 //! 1) OKDSetup01Inventory
 //!    - Serve default iPXE + Kickstart (in-RAM CentOS Stream 9) for discovery only.
-//!    - Enable SSH with the cluster’s ephemeral pubkey, start a Rust inventory agent.
+//!    - Enable SSH with the cluster’s pubkey, start a Rust inventory agent.
 //!    - Harmony discovers nodes by scraping the agent endpoint and collects MACs/NICs.
-//!    - DNS: optionally register temporary hostnames and enable DHCP lease registration.
 //!
 //! 2) OKDSetup02Bootstrap
 //!    - User selects which discovered node becomes bootstrap.
+//!    - Prepare the OKD cluster installation files
 //!    - Render per-MAC iPXE for bootstrap with OKD 4.19 SCOS live assets + ignition.
 //!    - Reboot node via SSH; install bootstrap; wait for bootstrap-complete.
 //!
 //! 3) OKDSetup03ControlPlane
-//!    - Render per-MAC iPXE for cp0/cp1/cp2 with ignition (includes persistent bond via
+//!    - Render per-MAC iPXE for cp0/cp1/cp2 with ignition. Reboot via SSH, join masters.
-//!      MachineConfig or NNCP if required). Reboot via SSH, join masters.
+//!    - Configure network bond (where relevant) using OKD NMState MachineConfig
 //!
 //! 4) OKDSetup04Workers
 //!    - Render per-MAC iPXE for worker set; join workers.
+//!    - Configure network bond (where relevant) using OKD NMState MachineConfig
 //!
 //! 5) OKDSetup05SanityCheck
 //!    - Validate API/ingress/clusteroperators; ensure healthy control plane and SDN.
@@ -49,33 +39,18 @@
 //!   do we set the bond persistently. If early bonding is truly required on a host,
 //!   use kernel args selectively in the per-MAC PXE for that host, but never for the
 //!   generic discovery path.
-//!
+//! - This is caused by the inherent race condition between PXE, which cannot perform
-//! DNS and hostname
+//!   its DHCP recovery process on a bonded network, and the bond configuration itself,
-//! - Because a single host may present multiple MACs, but DHCP/ISC on OPNsense may not
+//!   which must be configured on host AND switch to connect properly.
-//!   easily support “one hostname across multiple MACs” in a single lease entry, we avoid
-//!   strict hostname binding during discovery. We rely on dynamic leases and record the
-//!   mapping (IP/MAC) at scrape time.
-//! - Once a role is assigned, we render a per-MAC PXE entry and ensure the role-specific
-//!   DNS A/AAAA/CNAME entries are present (e.g., api, api-int, apps wildcard). This keeps
-//!   DHCP simple and DNS consistent for OKD.
-//!
-//! Instrumentation
-//! - All child Scores are executed via Score::interpret, which emits HarmonyEvent
-//!   InterpretExecutionStarted/Finished. The orchestrator also emits HarmonyStarted/
-//!   HarmonyFinished around the full pipeline execution.
 //!
 //! Configuration knobs
 //! - lan_cidr: CIDR to scan/allow for discovery endpoints.
 //! - public_domain: External wildcard/apps domain (e.g., apps.example.com).
 //! - internal_domain: Internal cluster domain (e.g., cluster.local or harmony.mcd).
-//!
-//! Notes
-//! - This file co-locates step Scores for ease of review. In follow-up changes, refactor
-//!   step Scores (OKDSetupXX*) into separate modules.
 
 use async_trait::async_trait;
 use derive_new::new;
-use harmony_macros::{ip, ipv4};
+use harmony_macros::ip;
 use log::info;
 use serde::{Deserialize, Serialize};
 
@@ -241,22 +216,16 @@ impl<T: Topology + DnsServer> Interpret<T> for OKDInstallationInterpret {
             self.score.public_domain, self.score.internal_domain, self.score.lan_cidr
         );
 
-        // 1) Inventory (default PXE, in-RAM kickstart, Rust inventory agent)
         self.run_inventory_phase(inventory, topology).await?;
 
-        // 2) Bootstrap (render per-MAC iPXE + ignition; reboot node; wait for bootstrap complete)
         self.run_bootstrap_phase(inventory, topology).await?;
 
-        // 3) Control plane
         self.run_control_plane_phase(inventory, topology).await?;
 
-        // 4) Workers
         self.run_workers_phase(inventory, topology).await?;
 
-        // 5) Sanity checks
         self.run_sanity_phase(inventory, topology).await?;
 
-        // 6) Installation report
         self.run_report_phase(inventory, topology).await?;
 
         instrument(HarmonyEvent::HarmonyFinished).ok();