Metal Component Specification

Root specification · Behavior: Metal codebase guide

Purpose

Metal manages virtual machines on a host with metald. It does not own the proxy or WG Mesh.

For Go code, follow the repository Go anti-pattern rules.

Layout

cmd/metald/     metald executable
internal/       packages, each with a SPEC.md
scripts/        host bootstrap scripts
test/           integration test data
Makefile        builds metald into dist/

The module path is github.com/frappe/atlas/metal. Run Go commands from metal/.

Packages

Package	Owns
vm	VM manager, records, and host service interfaces.
vm/migration	Live migration and its transport.
firecracker	Firecracker runtime and warm starts.
api	Thin HTTP handlers.
host	Host synchronization and capacity.
console	VM serial consoles over PTYs.
reconciler	VM and image loops.
storage	ZFS pool, disks, images, and snapshots.
network	VM networks and WireGuard peers.
platform	Host files, commands, systemd.
telemetry	Metrics push to Datum and the host collector.

Package imports

Package	Imports
cmd/metald	api, host, reconciler, firecracker, storage, network, vm/migration, network/traffic, telemetry
api	vm, host, console, vm/migration
host	vm, network, storage, vm/migration
reconciler	vm, storage, vm/migration
firecracker	vm, storage, platform, console, Firecracker API
storage	vm, platform
network	vm, platform, network/traffic
vm/migration	vm, storage, platform
network/traffic	cilium eBPF
api, vm, vm/migration, reconciler, storage, firecracker	telemetry
telemetry/system	telemetry, platform

vm must not import vm/migration. It reads migration locks through an injected guard.

Validation

See Metal development. The host layout lists each host file and dataset.