NationTech/harmony
6
0
Fork 1
Code Issues 32 Pull Requests 6 Actions 7 Packages Projects Releases 1 Wiki Activity

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

Browse Source
This commit is contained in:
Jean-Gabriel Gill-Couture 2025-08-19 12:42:15 -04:00
parent 56c181fc3d
commit c372e781d8
1 changed files with 12 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
harmony/src/modules/okd/installation.rs
View File

@ -2,39 +2,29 @@
//!
//! Overview
//! --------
//! 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
//! “discovery-first, then provision” strategy with strict ordering, observable progress,
//! 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.
//! OKDInstallationScore orchestrates an end-to-end, bare-metal OKD (OpenShift/OKD 4.19).
//! It follows principles of “discovery-first, then provision” strategy with strict ordering,
//! observable progress, and minimal assumptions about the underlying network.
//!
//! 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
//! MachineConfig or NNCP if required). Reboot via SSH, join masters.
//! - Render per-MAC iPXE for cp0/cp1/cp2 with ignition. 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.
//!
//! DNS and hostname
//! - Because a single host may present multiple MACs, but DHCP/ISC on OPNsense may not
//! 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.
//! - This is caused by the inherent race condition between PXE, which cannot perform
//! its DHCP recovery process on a bonded network, and the bond configuration itself,
//! which must be configured on host AND switch to connect properly.
//!
//! 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();