Capítulo 3: Tu Primera microVM

En este capítulo arrancarás una microVM completa usando Firecracker. Necesitarás dos terminales abiertas simultáneamente.

Lo que necesitas

Tres componentes obligatorios para arrancar una microVM:

1. Kernel Linux (vmlinux) — sin comprimir, formato ELF
2. Rootfs — imagen ext4 del sistema de archivos raíz
3. Binario Firecracker — el VMM

Si seguiste el capítulo anterior, ya tienes vmlinux y rootfs.ext4 en ~/firecracker-lab/.

Flujo de arranque

sequenceDiagram
    participant C as Cliente (curl)
    participant FC as Firecracker
    participant KVM as KVM / CPU

    C->>FC: PUT /boot-source (kernel)
    C->>FC: PUT /drives/rootfs (disco)
    C->>FC: PUT /machine-config (CPU/RAM)
    C->>FC: PUT /actions InstanceStart
    FC->>KVM: KVM_CREATE_VM
    KVM-->>FC: VM handle
    FC->>KVM: KVM_RUN (vCPU)
    Note over KVM: Guest Linux arranca

Terminal 1: Arrancar Firecracker

cd ~/firecracker-lab

# Limpiar socket anterior si existe
API_SOCKET="/tmp/firecracker.socket"
rm -f "${API_SOCKET}"

# Iniciar Firecracker (queda esperando configuración via socket)
firecracker --api-sock "${API_SOCKET}"

Firecracker queda bloqueado esperando peticiones. No cierres esta terminal.

Terminal 2: Configurar y arrancar la VM

Abre una segunda terminal:

cd ~/firecracker-lab
API_SOCKET="/tmp/firecracker.socket"

# 1. Configurar el kernel
curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{
    "kernel_image_path": "./vmlinux",
    "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
  }' \
  "http://localhost/boot-source"

# 2. Configurar el disco raíz
curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{
    "drive_id": "rootfs",
    "path_on_host": "./rootfs.ext4",
    "is_root_device": true,
    "is_read_only": false
  }' \
  "http://localhost/drives/rootfs"

# 3. Configurar CPU y memoria
curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{
    "vcpu_count": 2,
    "mem_size_mib": 1024
  }' \
  "http://localhost/machine-config"

# 4. ARRANCAR la microVM
curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{"action_type": "InstanceStart"}' \
  "http://localhost/actions"

Vuelve a la Terminal 1 — deberías ver el boot de Linux en la consola serial.

Iniciar sesión en el guest

Con el rootfs de prueba de Ubuntu:

login: root
password: root

Para salir del guest sin matar el proceso, escribe reboot — Firecracker terminará porque el kernel hace reboot=k (kernel panic en reboot, detiene la VM limpiamente).

Alternativa: archivo de configuración JSON

En lugar de múltiples llamadas curl, puedes configurar todo en un archivo:

cat > vm_config.json << 'EOF'
{
  "boot-source": {
    "kernel_image_path": "./vmlinux",
    "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
  },
  "drives": [
    {
      "drive_id": "rootfs",
      "path_on_host": "./rootfs.ext4",
      "is_root_device": true,
      "is_read_only": false
    }
  ],
  "machine-config": {
    "vcpu_count": 2,
    "mem_size_mib": 1024
  }
}
EOF

# Arrancar con archivo de config (no necesita Terminal 2)
firecracker --api-sock /tmp/fc.sock --config-file vm_config.json

Entender los parámetros de boot

Parámetro	Propósito
console=ttyS0	Redirige la consola del guest al serial port
reboot=k	Kernel panic en lugar de reboot (limpia el proceso)
panic=1	Apaga después de 1 segundo si hay kernel panic
pci=off	Deshabilita PCI (no usado, simplifica el arranque)

Firecracker agrega automáticamente algunos parámetros adicionales como nomodule, 8250.nr_uarts=0 y configuraciones de i8042.

Verificar el estado de la VM

Mientras la VM corre, desde otra terminal:

# Consultar estado
curl -s --unix-socket /tmp/firecracker.socket \
  "http://localhost/machine-config"

# Ver metadatos de la instancia
curl -s --unix-socket /tmp/firecracker.socket \
  "http://localhost/version"

Próximos pasos

La VM está aislada — no tiene red. En el Capítulo 5 configuraremos conectividad de red. Antes, en el Capítulo 4 veremos todos los endpoints de la API REST disponibles.

Referencia

• getting-started.md
• kernel-policy.md