← Volver al listado de tecnologías ← Índice de Firecracker

Capítulo 4: La API REST de Firecracker

4 de abril de 2026 Por: Artiko

firecrackerapi-restunix-sockethttpendpoints

Capítulo 4: La API REST

Firecracker expone toda su funcionalidad a través de una API HTTP sobre Unix domain socket. No hay TCP, no hay autenticación — el acceso se controla mediante permisos del sistema de archivos sobre el socket.

Comunicación via Unix socket

# Formato básico de todas las peticiones
curl --unix-socket /tmp/firecracker.socket \
  -X <MÉTODO> \
  --header "Content-Type: application/json" \
  --data '<JSON>' \
  "http://localhost/<endpoint>"

El http://localhost es necesario para que curl forme el request HTTP correctamente, pero la conexión TCP nunca llega a resolverse — va directo al socket Unix.

Endpoints principales

Estado e información

# Versión de Firecracker
GET /version

# Estado de la VM (Not started | Running | Paused)
GET /vm

# Configuración actual de la máquina
GET /machine-config

# Métricas (si están configuradas)
GET /metrics

Configuración (solo antes de InstanceStart)

# Kernel y parámetros de boot
PUT /boot-source

# Disco raíz y discos adicionales
PUT /drives/{drive_id}

# Interfaces de red
PUT /network-interfaces/{iface_id}

# CPU y memoria
PUT /machine-config

# Vsock
PUT /vsock

# MMDS (metadata service)
PUT /mmds/config

Control del ciclo de vida

# Acciones sobre la VM
PUT /actions
# body: { "action_type": "InstanceStart" | "SendCtrlAltDel" | "FlushMetrics" }

# Cambiar estado (pausar/resumir)
PATCH /vm
# body: { "state": "Paused" | "Resumed" }

Snapshots

# Crear snapshot
PUT /snapshot/create

# Restaurar snapshot (antes de InstanceStart)
PUT /snapshot/load

Recursos dinámicos (durante ejecución)

# Actualizar configuración de balloon
PATCH /balloon
GET /balloon
GET /balloon/statistics

# Agregar memoria (memory hotplug)
PUT /memory/regions/{region_id}

# Actualizar drive existente
PATCH /drives/{drive_id}

# Actualizar rate limiter de red
PATCH /network-interfaces/{iface_id}

Ejemplos completos

Consultar estado actual

API_SOCKET="/tmp/firecracker.socket"

curl -s --unix-socket "${API_SOCKET}" \
  "http://localhost/machine-config" | jq .

Respuesta esperada:

{
  "vcpu_count": 2,
  "mem_size_mib": 1024,
  "smt": false,
  "track_dirty_pages": false
}

Configurar balloon device

curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount_mib": 256,
    "deflate_on_oom": true,
    "stats_polling_interval_s": 1
  }' \
  "http://localhost/balloon"

Actualizar un drive en caliente

Firecracker soporta actualizar la ruta de un drive mientras la VM corre (útil para swap de imágenes):

curl -s -X PATCH \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{
    "drive_id": "data",
    "path_on_host": "./new-data.ext4"
  }' \
  "http://localhost/drives/data"

Enviar Ctrl+Alt+Del al guest

curl -s -X PUT \
  --unix-socket "${API_SOCKET}" \
  --header "Content-Type: application/json" \
  --data '{"action_type": "SendCtrlAltDel"}' \
  "http://localhost/actions"

Códigos de respuesta HTTP

Código	Significado
200 OK	Consulta exitosa
204 No Content	Operación exitosa sin respuesta
400 Bad Request	JSON inválido o parámetros incorrectos
404 Not Found	Recurso no encontrado
405 Method Not Allowed	Método HTTP incorrecto
500 Internal Server Error	Error interno del VMM
501 Not Implemented	Funcionalidad no disponible

Script helper

Un pequeño wrapper para simplificar las llamadas:

#!/bin/bash
# fc-api.sh — helper para la API de Firecracker
SOCKET="${FC_SOCKET:-/tmp/firecracker.socket}"

fc_get() {
  curl -sf --unix-socket "${SOCKET}" "http://localhost/$1"
}

fc_put() {
  curl -sf -X PUT \
    --unix-socket "${SOCKET}" \
    --header "Content-Type: application/json" \
    --data "$2" \
    "http://localhost/$1"
}

fc_patch() {
  curl -sf -X PATCH \
    --unix-socket "${SOCKET}" \
    --header "Content-Type: application/json" \
    --data "$2" \
    "http://localhost/$1"
}

# Uso:
# source fc-api.sh
# fc_get machine-config
# fc_put actions '{"action_type":"InstanceStart"}'

Especificación OpenAPI

La especificación completa de la API en formato OpenAPI/Swagger está disponible en el repositorio:

firecracker.yaml

Puedes importarla en Postman o cualquier cliente OpenAPI para explorar todos los endpoints con autocompletado.