How igr1s-red/spinup works
Project Type and Purpose
• This is a standalone CLI tool written in Go for "spinning up" Linux virtual machines using QEMU.
• It provides end‐user commands (run, exec, ssh, start, stop, remove, etc.) to automate VM lifecycle: creating disk images, generating cloud-init config, invoking QEMU, and managing SSH access.
Main Components
A. CLI Layer (cmd package)
• All user‐facing commands live under cmd/*.go (run, exec, ssh, list, remove, etc.).
• Parses flags, validates arguments, and dispatches to the Engine API.
B. Engine Core (engine package)
• Central business logic in engine/engine.go: orchestration of VM creation, state management, image handling.
• Error definitions, path management, VM struct definitions.
C. CloudInit Generator (cloudinit package)
• cloudinit/cloudinit.go produces the ISO or user-data config for QEMU to inject SSH keys and initial provisioning.
D. QEMU Wrapper (qemu package)
• qemu/qemu.go builds the exec.Command invocation for qemu-system-<arch> and qemu-img.
• Encapsulates external binary calls and argument construction.
E. External Binaries
• qemu-img, qemu-system-aarch64 or qemu-system-x86_64 on the host.
F. Virtual Machine Instance
• The running guest, reached by SSH over a forwarded port.
Component Interactions and Data Flow
• User types spinup run … → CLI Layer parses it → calls Engine.Run()
• Engine:
1. Generates SSH key pair (if needed)
2. Calls CloudInit to render a seed ISO with user-data
3. Uses QEMU Wrapper to:
• Create or resize disk image via qemu-img
• Launch qemu-system with CPU, memory, disk, CD-ROM (cloud-init) and port-forward options
• QEMU binary boots the VM, reads cloud-init ISO for provisioning
• User can then run spinup ssh or spinup exec, which again goes CLI → Engine → QEMU wrapper (with -serial or ssh commands)
Architectural Patterns and Principles
• Layered Modularization:
• CLI layer strictly handles parsing and help text.
• Engine layer exposes a clean Go API for VM lifecycle.
• CloudInit and QEMU packages isolate external concerns.
• Single Responsibility: each package has one clear focus.
• Dependency Inversion: Engine depends on abstracted QEMU/CloudInit interfaces, making it easy to mock for tests.