How cray-hpe/metal-init works
Project type & purpose (what you’re diagramming)
This is not a typical service/app; it’s an operations/tooling repository: a Pre-Install Toolkit (PIT) automation bundle made of shell scripts + config artifacts intended to run inside (or emulate) a Cray Pre-Install Toolkit environment.
• Execution environment(s) (PIT live image / emulated PIT)
• Operator entrypoints
• Script modules grouped by function (BIOS, networking, NTP, image/SQFS handling, initialization)
• External systems/devices the scripts control (BMC/IPMI, NICs/bonds/VLANs, time sources)
• Artifacts (INI/JSON configs, spec file, Makefile) and CI automation (GitHub workflows, Jenkinsfile)
A good mental model: a toolkit pipeline that configures bare-metal nodes pre-install.
File structure analysis → architectural modules
Top-level structure is flat, but the bin/ directory is the product.
Core modules (by file grouping)
A. BIOS / hardware baseline
• bin/bios-baseline.sh
• bin/bios-hpe-baseline.ini (baseline settings)
• bin/bios-hpe-enable-ipmitool.json (likely vendor/tool-specific config/commands)
B. Network bring-up / CSI (node) setup
• bin/csi-pxe-bond0.sh
• bin/csi-pxe-hmn.sh
• bin/csi-set-hostname.sh
• bin/csi-setup-bond0.sh
• bin/csi-setup-hmn.sh
• bin/csi-setup-lan0.sh
These suggest a sequence: PXE context scripts vs post-boot setup scripts; configuring interfaces like bond0, HMN, lan0, and setting hostname.
C. Time configuration
• bin/configure-ntp.sh
D. PIT initialization / identity
• bin/pit-init.sh
• bin/metalid.sh (likely generates/reads a “metal ID”, serial, MAC-based identifier, etc.)
E. Image / filesystem artifacts (SQFS)
• bin/get-sqfs.sh
• bin/set-sqfs-links.sh
This implies interactions with a remote artifact store or local cache; the PIT environment may mount or link squashfs images.
Packaging / build / CI artifacts
• Makefile (local build/test/lint/package tasks)
• metal-init.spec (RPM spec packaging)
• .github/workflows/* (labeling, merge strategy, shellcheck, stale issues)
• Jenkinsfile.github (CI pipeline, likely for enterprise Jenkins mirroring GitHub)
README insights
README is minimal but confirms the key: “scripts and config files for running on a Cray Pre-Install Toolkit, or emulating such an environment.”
Initialization & Identity
• pit-init.sh
• metalid.sh
• Outputs: machine identity facts, initialization state, maybe local files under /etc or /var
BIOS Baseline
• bios-baseline.sh
• Inputs: bios-hpe-baseline.ini, bios-hpe-enable-ipmitool.json
• External: BMC/IPMI / vendor BIOS interface
• Outputs: BIOS settings applied, logs
Networking (CSI Setup)
• csi-setup-bond0.sh, csi-pxe-bond0.sh
• csi-setup-hmn.sh, csi-pxe-hmn.sh
• csi-setup-lan0.sh
• csi-set-hostname.sh
• External: NICs, OS network stack, potentially DHCP/PXE environment
• Outputs: interface configs, routes, hostname, link state
Time Sync
• configure-ntp.sh
• External: NTP servers
• Outputs: NTP client config / service state
Image/Artifact Handling
• get-sqfs.sh
• set-sqfs-links.sh
• External: artifact store
• Outputs: downloaded SQFS, symlinks/mount points
“Packaging & Delivery” as a separate lane (not inside runtime):
• metal-init.spec → RPM build artifact
• Makefile → build/lint/package entrypoints
• GitHub Workflows / Jenkinsfile → CI gates (ShellCheck, labeling)
• BIOS baseline may be independent or early; if it requires network/BMC access, show that dependency.
• Lane 1: Operator / Orchestrator
• Lane 2: PIT Environment
• Lane 3: Target Node / OS config
• Lane 4: BMC/IPMI
• Lane 5: Artifact repo / NTP servers
Result: node is baseline-ready for subsequent install stages
Make it explicit which steps are idempotent (likely intended) and which require reboots (BIOS changes often do).
Important architectural patterns/design principles to highlight
• Config-driven operations: INI/JSON files parameterize behavior (BIOS baseline).
• Environment-dependent execution: PIT vs emulated PIT.
• Imperative orchestration: scripts act as runbooks encoded as code.
• Separation by concerns: BIOS vs network vs NTP vs artifact retrieval.
• Packaging for distribution: RPM spec indicates this is meant to be installed as a package, not just cloned.
Technologies/frameworks to include (what matters here)
• Shell scripts (bash/sh) as primary runtime
• IPMI / vendor BIOS tooling (implied by “ipmitool” config and BIOS scripts)
• NTP (client config + NTP servers)
• PXE context (explicit in script names)
• SquashFS (SQFS) artifact handling
• CI: GitHub Actions (ShellCheck), Jenkins pipeline
• Packaging: RPM (metal-init.spec), Makefile build targets