How ftiradob/microvm_firecracker works
Project type and purpose
• This is a CLI‐driven orchestration tool for launching and managing Firecracker microVMs on a Linux host.
• It bundles:
• automicrovm.sh – a shell script that drives the overall workflow
• firecracker – the core microVM runtime binary (Rust/KVM)
• firectl – a convenience wrapper around Firecracker’s API
• imagenes/ – prebuilt kernel+rootfs images (Alpine, Debian)
File structure
• Top‐level files:
• automicrovm.sh: main entry-point for user interaction
• firecracker & firectl: binaries invoked by the script
• imagenes/: VM guest artifacts (vmlinuz.bin, .ext4 files)
• No classic “src/backend/frontend” hierarchy—instead the architecture revolves around host tooling, VM artifacts, and runtime binaries.
Key points from the README
• Two modes of invoking Firecracker:
a. Directly via REST API socket + curl
b. Via JSON config + single Firecracker invocation
• Firectl abstracts away manual socket/JSON steps into flags.
• Script automates: OS choice, vCPU/RAM, tap0 network setup, iptables, dynamic socket naming, VM launch.
• Under the hood: Firecracker leverages Linux KVM for isolation & performance, and uses a minimal Linux kernel + ext4 rootfs.
Main components
A. User & CLI Layer
• User types commands in automicrovm.sh → script logic
B. Orchestration Layer
• automicrovm.sh calls:
• firectl (with flags) OR
• firecracker + JSON/REST API
C. Host Runtime Layer
• Firecracker process(es)
→ interacts with Linux KVM kernel module
• Host network utilities
→ creates tap0, iptables rules
D. VM Guest Instances
• Each microVM process:
• Kernel (vmlinuz.bin)
• Root filesystem (ext4 image)
• Virtual devices (vCPU, RAM, virtio‐fs, network)
E. External Network / Host Filesystem
• VM network traffic flows via tap0 → host forwarding → external network
• VM rootfs images stored on host filesystem (imagenes/)
Relationships & interactions
• automicrovm.sh → invokes firectl/firecracker
• firecracker ↔ KVM (via ioctls) to spin up VM context
• firecracker ↔ VM images (kernel & rootfs) as block devices
• firecracker exposes a UNIX socket for API calls (boot, drive attach, machine config, start)
• Host network stack ↔ tap0 interface ↔ microVM virtual NIC
• VM ↔ host (storage) through mapped ext4 image files
Architectural patterns & design principles
• Component separation: orchestration (script) vs. runtime (binaries) vs. VM artifacts
• Extensibility: Swap in new OS images or adjust JSON configs without changing code
• Infrastructure as code: All VM parameters declared as shell flags or JSON
• OS‐level virtualization: Minimal overhead by leveraging KVM + microVM approach
Technologies & libraries
• Bash shell scripting
• Firecracker (Rust/KVM)
• Firectl wrapper (Go or Rust)
• Linux network tooling (ip, iptables, tap devices)
• ext4 rootfs images, Docker (for image building), dd/mkfs
Final advice
• Essential pieces, but keep the drawing uncluttered:
separate orchestration, runtime, VM, and host infra into horizontal layers.
• Don’t hesitate to break out the Firecracker API socket and JSON config as their own mini‐component if it helps clarify how the script communicates with the runtime.