NationTech/harmony
3
0
Fork 2
Code Issues 38 Pull Requests 29 Actions Packages Projects Releases 1 Wiki Activity
Files
master
harmony/examples/fleet_vm_setup/README.md
Jean-Gabriel Gill-Couture 7c1fedb303
All checks were successful
Run Check Script / check (pull_request) Successful in 2m25s
Details
refactor: rebrand iot → fleet, operator/agent crates → harmony-fleet-* 
The IoT vocabulary was anchoring the codebase to one customer's
domain. The reconciler pattern is generic — operator in k8s, NATS
KV as desired-state bus, agents reconciling podman / OKD / KVM /
anything that can register. "Fleet" captures that neutrally; IoT
stays acknowledged in docs as the first customer use case.

Done now, while nothing is deployed. After a partner fleet lands,
changing the CRD group alone is a multi-quarter migration.

Scope (nothing left over):

Paths + crates
- iot/ → fleet/
- iot/iot-operator-v0 → fleet/harmony-fleet-operator
- iot/iot-agent-v0 → fleet/harmony-fleet-agent
- harmony/src/modules/iot → harmony/src/modules/fleet
- ROADMAP/iot_platform → ROADMAP/fleet_platform
- examples/iot_{vm_setup, load_test, nats_install} → examples/fleet_*
- -v0 suffix dropped on the operator + agent crates (semver in
  Cargo.toml already tracks version)

Rust identifiers
- enum IotScore (podman score payload) → ReconcileScore
- struct IotDeviceSetupScore/Config → FleetDeviceSetupScore/Config
- InterpretName::IotDeviceSetup → InterpretName::FleetDeviceSetup
- HarmonyIotPool → HarmonyFleetPool (libvirt pool)
- HARMONY_IOT_POOL_NAME (default "harmony-iot") → HARMONY_FLEET_POOL_NAME ("harmony-fleet")
- IotSshKeypair → FleetSshKeypair
- ensure_iot_ssh_keypair / ensure_harmony_iot_pool /
  check_iot_smoke_preflight_for_arch → fleet-prefixed variants

Wire / config surfaces
- CRD group `iot.nationtech.io` → `fleet.nationtech.io`
- Finalizer `iot.nationtech.io/finalizer` → `fleet.nationtech.io/finalizer`
- Shortnames iotdep/iotdevice → fleetdep/fleetdev
- Env var IOT_AGENT_CONFIG → FLEET_AGENT_CONFIG
- Env var IOT_VM_ADMIN_PASSWORD → FLEET_VM_ADMIN_PASSWORD
- Binary /usr/local/bin/iot-agent → /usr/local/bin/fleet-agent
- Systemd user `iot-agent` → `fleet-agent`
- VM admin user `iot-admin` → `fleet-admin`

Defaults
- Namespaces iot-system/iot-demo/iot-load → fleet-system/fleet-demo/fleet-load
- Helm release iot-nats → fleet-nats
- Helm release iot-operator-v0 → harmony-fleet-operator
- Container image localhost/iot-operator-v0:latest →
  localhost/harmony-fleet-operator:latest
- On-disk cache $HARMONY_DATA_DIR/iot/ → $HARMONY_DATA_DIR/fleet/
  (cloud-images, ssh keypairs, libvirt pool)

What stayed
- harmony-reconciler-contracts — already neutrally named
- Wire types (DeviceInfo, DeploymentState, HeartbeatPayload,
  DeploymentName) — already neutral
- KV buckets (device-info, device-state, device-heartbeat,
  desired-state) — already neutral
- CRD kind names (Deployment, Device) — already neutral
- NatsBasicScore / NatsHelmChartScore / HelmChart / etc. —
  framework-scope, unchanged

Verification
- cargo check --workspace --all-targets: clean
- All harmony lib tests (114), fleet-operator (6), fleet-agent
  (7), harmony-reconciler-contracts (13): green
- End-to-end load-test (20 devices / 3 CRs / 20s under
  fleet/scripts/load-test.sh): PASS. Image built as
  localhost/harmony-fleet-operator:latest, chart installed as
  release harmony-fleet-operator in namespace fleet-system,
  all CR aggregates correct.

Zero stragglers: grep across the tree for \biot\b / IOT_ /
\bIot[A-Z] returns empty (excluding docs explicitly talking about
IoT as the first customer's domain).
2026-04-23 11:10:10 -04:00

2.3 KiB
Raw Permalink Blame History

example_iot_vm_setup

End-to-end driver for the IoT walking-skeleton VM-as-device flow. Runs two Harmony Scores in sequence:

  1. KvmVmScore — provision a libvirt VM from an Ubuntu 24.04 cloud image with a cloud-init seed ISO that authorizes one SSH key. Returns the booted VM's IP.
  2. FleetDeviceSetupScore — SSH into the VM (via the Ansible-backed HostConfigurationProvider) and install podman + the fleet-agent binary, drop the TOML config, bring up the systemd unit.

After a successful run, the VM is a fleet member reporting to NATS under the --device-id you chose, carrying the --group label you passed.

One-time setup

WORK=/var/tmp/harmony-iot-smoke
mkdir -p "$WORK/ssh"

# 1. Ubuntu 24.04 cloud image (~700 MB) — cached between runs.
curl -o "$WORK/ubuntu-24.04-server-cloudimg-amd64.img" \
     https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img

# 2. SSH keypair the VM will trust.
ssh-keygen -t ed25519 -N '' -f "$WORK/ssh/id_ed25519"

# 3. Runtime deps — Harmony self-installs Ansible into a managed venv
#    under $HARMONY_DATA_DIR/ansible-venv on first run, so you only need
#    python3 + venv on the runner. No system-wide `ansible` needed.
# On Arch:
#   sudo pacman -S libvirt qemu-full xorriso python
# On Debian/Ubuntu:
#   sudo apt install libvirt-daemon-system qemu-kvm xorriso python3 python3-venv

# 4. libvirt default network.
sudo virsh net-start default
sudo virsh net-autostart default

Run

cargo build -p fleet-agent-v0

cargo run -p example_iot_vm_setup -- \
  --base-image /var/tmp/harmony-iot-smoke/ubuntu-24.04-server-cloudimg-amd64.img \
  --ssh-pubkey /var/tmp/harmony-iot-smoke/ssh/id_ed25519.pub \
  --ssh-privkey /var/tmp/harmony-iot-smoke/ssh/id_ed25519 \
  --work-dir /var/tmp/harmony-iot-smoke \
  --agent-binary target/debug/fleet-agent-v0 \
  --nats-url nats://192.168.122.1:4222

Changing groups

Re-running with a different --group rewrites /etc/fleet-agent/config.toml on the VM and restarts the agent. The VM itself is untouched.

cargo run -p example_iot_vm_setup -- ... --group group-b

Full end-to-end via smoke test

See fleet/scripts/smoke-a3.sh — stands up NATS in a podman container, runs this example, asserts the agent's status lands in NATS.