manta_server/service/hw_cluster/
mod.rs

1//! Hardware-cluster pin/unpin and hw-component add/delete service logic.
2//!
3//! # Model
4//!
5//! CSM groups nodes into HSM groups. A *parent* group holds the
6//! shared pool; a *target* group represents a sub-pool reserved for a
7//! particular workload. "Pinning" moves nodes from the parent into
8//! the target so that the target satisfies a user-supplied hardware
9//! pattern (e.g. `a100:8,milan:2` — eight A100s and two Milan CPUs).
10//! "Unpinning" is the reverse: nodes are released back to the parent.
11//!
12//! Both operations are framed as a search over candidate moves where
13//! each candidate is scored by how *useful* a node is for the target
14//! workload, with a scarcity weighting that prefers giving up common
15//! components and keeping rare ones. See `scoring` for the rubric.
16//!
17//! # Layout
18//!
19//! Split into four (private) sub-modules plus shared types:
20//!
21//! - `scoring` — pure-computation functions for component scarcity,
22//!   per-node scoring, candidate selection, pattern parsing, and the
23//!   parallel hw-inventory fetcher. Also hosts
24//!   `resolve_hw_description_to_xnames`, which dispatches between
25//!   pin and unpin.
26//! - `pin_unpin` — the `calculate_target_group_pin` / `_unpin` node
27//!   selection algorithms plus the shared coordination helpers used
28//!   by `apply_hw_configuration` (pattern parsing, target-group
29//!   existence check, resource-sufficiency validation, group-update
30//!   orchestration).
31//! - `apply` — high-level coordinators called by the server
32//!   handlers: `apply_hw_configuration`, `add_hw_component`,
33//!   `delete_hw_component`.
34//! - `hw_inventory_utils` — JSON-pointer helpers that extract memory,
35//!   processor, and accelerator data from raw HSM inventory payloads.
36//!
37//! Public types (`AddHwResult`, `DeleteHwResult`, `ApplyHwResult`,
38//! `NodeHwCountVec`, `HwClusterMode`) and shared constants live here
39//! so all sub-modules can use them. The public surface is re-exported
40//! at the bottom of this file; callers (the `hw_cluster` handlers
41//! under `crate::server::handlers`) should depend only on those
42//! re-exports.
43
44use std::collections::HashMap;
45
46mod apply;
47mod hw_inventory_utils;
48mod pin_unpin;
49mod scoring;
50
51/// LCM (Least Common Multiple) used to normalise memory capacity values.
52/// Memory DIMMs come in multiples of 16 GiB (16384 MiB).
53pub(in crate::service::hw_cluster) const MEMORY_CAPACITY_LCM: u64 = 16384;
54
55/// Maximum number of concurrent hardware component queries.
56pub(in crate::service::hw_cluster) const HW_COMPONENT_CONCURRENCY_LIMIT: usize =
57  5;
58
59// ── Public types ────────────────────────────────────────────────────────────
60
61pub use manta_shared::types::api::hw_cluster::HwClusterMode;
62
63/// A list of nodes paired with their per-component counts.
64pub type NodeHwCountVec = Vec<(String, HashMap<String, usize>)>;
65
66/// Result of an `add hw-component` operation.
67pub struct AddHwResult {
68  /// Xnames moved from the parent group into the target group as
69  /// part of this operation.
70  pub nodes_moved: Vec<String>,
71  /// Final membership of the target group after the move.
72  pub target_nodes: Vec<String>,
73  /// Final membership of the parent group after the move.
74  pub parent_nodes: Vec<String>,
75}
76
77/// Result of a `delete hw-component` operation.
78pub struct DeleteHwResult {
79  /// Xnames moved out of the target group and returned to the
80  /// parent group as part of this operation.
81  pub nodes_moved: Vec<String>,
82  /// Final membership of the target group after the move.
83  pub target_nodes: Vec<String>,
84  /// Final membership of the parent group after the move.
85  pub parent_nodes: Vec<String>,
86}
87
88/// Result of an `apply hw-configuration` (pin/unpin) operation.
89pub struct ApplyHwResult {
90  /// Final membership of the target group after pin/unpin completes.
91  pub target_nodes: Vec<String>,
92  /// Final membership of the parent group after pin/unpin completes.
93  pub parent_nodes: Vec<String>,
94}
95
96// ── External API (re-exported from sub-modules) ─────────────────────────────
97
98pub use apply::{
99  ApplyHwConfigurationParams, add_hw_component, apply_hw_configuration,
100  delete_hw_component,
101};
102
103#[cfg(test)]
104mod tests;
manta_server/service/hw_cluster/mod.rs

manta_server/service/hw_cluster/
mod.rs
