# ftiradob/microvm_firecracker architecture

> Architecture diagram of the GitHub repository ftiradob/microvm_firecracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ftiradob/microvm_firecracker
- Repository: https://github.com/ftiradob/microvm_firecracker

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User & CLI Layer"
        User["User"]
        CLI["automicrovm.sh"]:::host
        User -->|"runs"| CLI
    end

    subgraph "Orchestration Layer"
        CLI -->|"invokes"| Firectl["firectl"]:::host
        CLI -->|"invokes"| FC_API["firecracker + JSON/REST"]:::host
        Firectl -->|"calls API"| FC_API
    end

    subgraph "Host Runtime Layer"
        KVM["Linux KVM Module"]:::host
        NetStack["Host Network Stack"]:::host
        tap["tap0 Interface"]:::network
        Iptables["iptables Rules"]:::network
        FC_API -->|"ioctls"| KVM
        FC_API -->|"uses"| Storage["VM Images (imagenes/)"]:::storage
        FC_API -->|"exposes socket"| Socket["API Unix Socket"]:::host
        NetStack --> tap
        NetStack --> Iptables
    end

    subgraph "Fleet of microVMs"
        direction TB
        VM1["MicroVM #1"]:::guest
        VM2["MicroVM #2"]:::guest
        VM1 -->|"vNIC"| tap
        VM2 -->|"vNIC"| tap
        VM1 -->|"rootfs"| Img1["alpine.ext4"]:::storage
        VM1 -->|"kernel"| KImg1["alpine-vmlinuz.bin"]:::storage
        VM2 -->|"rootfs"| Img2["debian.ext4"]:::storage
        VM2 -->|"kernel"| KImg2["debian-vmlinuz.bin"]:::storage
    end

    subgraph "External Network"
        Internet["External Network"]:::network
        tap -->|"NAT"| Internet
    end

    click CLI "https://github.com/ftiradob/microvm_firecracker/blob/master/automicrovm.sh"
    click Firectl "https://github.com/ftiradob/microvm_firecracker/tree/master/firectl"
    click FC_API "https://github.com/ftiradob/microvm_firecracker/tree/master/firecracker"
    click Storage "https://github.com/ftiradob/microvm_firecracker/tree/master/imagenes/"
    click KImg1 "https://github.com/ftiradob/microvm_firecracker/blob/master/imagenes/alpine-vmlinuz.bin"
    click Img1 "https://github.com/ftiradob/microvm_firecracker/blob/master/imagenes/alpine.ext4"
    click KImg2 "https://github.com/ftiradob/microvm_firecracker/blob/master/imagenes/debian-vmlinuz.bin"
    click Img2 "https://github.com/ftiradob/microvm_firecracker/blob/master/imagenes/debian.ext4"

    classDef host fill:#ADD8E6,stroke:#000
    classDef guest fill:#90EE90,stroke:#000
    classDef storage fill:#F5DEB3,stroke:#000
    classDef network fill:#FFE4B5,stroke:#000
```
