Volver a actualizaciones
Nuevo releaseAug 14, 2026

holos v0.6.2

Herramienta declarativa de orquestación de máquinas virtuales KVM/QEMU que utiliza archivos de composición YAML. Gestiona pilas de múltiples VMs con cloud-init, SSH, paso PCI y verificación de imágenes sin libvirt ni XML.

Compartir
holos

Docker compose para KVM. Define stacks multi-VM en un único archivo YAML. Sin libvirt, sin XML, sin plano de control distribuido.

Sitio web y documentación: https://zeroecco.github.io/holos/

La primitiva es una VM, no un contenedor. Cada instancia de carga de trabajo obtiene su propia frontera de kernel, overlay qcow2, seed de cloud-init y acceso SSH generado.

Empieza aquí

Ejecuta VMs en un host Linux con /dev/kvm, QEMU y un generador de seeds de cloud-init. Consulta requisitos del host. Las compilaciones para macOS permiten la creación, la descarga de imágenes y la validación; no pueden ejecutar VMs KVM.

Instalación

Los binarios precompilados se adjuntan a cada GitHub release:

Este ejemplo instala la compilación para Linux x86-64. Utiliza curl, tar, sha256sum y la CLI de GitHub (gh) para la verificación de procedencia. Para otras plataformas, elige el archivo correspondiente en la página de releases.

(
set -e
TAG=v0.7.1
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -fLO $BASE/$ASSET
curl -fLO $BASE/checksums.txt
grep " $ASSET$" checksums.txt | sha256sum -c -
gh attestation verify $ASSET --repo zeroecco/holos
sudo tar -xz -C /usr/local/bin -f $ASSET holos
holos version
holos doctor
)

Las páginas de lanzamiento incluyen sumas de verificación SHA-256 y atestaciones de artefactos de GitHub para procedencia firmada. Verifique ambas antes de instalar binarios en hosts de producción.

O bien, desde una copia de este repositorio con Go 1.26 instalado, compile desde el código fuente:

go build -o bin/holos ./cmd/holos
export PATH="$PWD/bin:$PATH"
holos doctor

Prueba una VM

Usa un nombre fijo para que todos los comandos a continuación funcionen tal como están escritos:

holos run --name try-holos alpine
holos exec -w 5m try-holos

Ahora estás en el guest. Ejecuta cat /etc/os-release, luego exit para volver al host. Desde el host:

holos stop try-holos    # keep the guest disk
holos start try-holos
holos exec try-holos

Salga del invitado de nuevo y, a continuación, elimine la VM desechable:

holos down try-holos   # deletes its guest disk

Ejecutar un servicio web

Cree un directorio vacío y guarde esto como holos.yaml:

name: hello

services:
  web:
    image: ubuntu:noble
    ports:
      - "8080:80"
    cloud_init:
      packages: [nginx]
      write_files:
        - path: /var/www/html/index.html
          content: "hello from holos\n"
      runcmd:
        - systemctl restart nginx

Desde ese directorio:

holos up
holos exec -w 5m web -- sudo cloud-init status --wait
curl --fail localhost:8080

Espera hello from holos. La espera es importante: up inicia la VM, pero nginx se instala durante el primer arranque. Si el aprovisionamiento falla, lee holos logs web.

Uso diario

Dentro de un directorio de proyecto:

holos exec web       # guest shell; exit returns to the host
holos logs web      # boot and provisioning logs
holos stop web      # keep its disk
holos start web
holos up --dry-run  # preview changes after editing holos.yaml
holos help exec     # syntax and options

Usa un nombre de instancia como web-0 cuando un servicio tenga múltiples réplicas. Los cambios que reemplazan o eliminan una VM requieren holos up --recreate; revisa primero la vista previa porque el reemplazo elimina el disco raíz de esa VM. Los volúmenes con nombre sobreviven. Consulta la guía de actualización antes de actualizar proyectos creados por una versión anterior.

Cuando termines con este stack desechable:

holos down hello

stop conserva los discos de la instancia. down los elimina; los volúmenes con nombre permanecen hasta que se eliminen explícitamente. Consulta la guía de la CLI para instantáneas, volúmenes, bloqueos de imágenes y configuración de systemd.

Documentación

  • Sitio web: página de inicio y documentación renderizada.
  • Guía de la CLI: VMs ad hoc, exec, instalación de systemd, importación con virsh y doctor.
  • Archivo Compose: servicios, volúmenes, healthchecks, redes, PCI passthrough, aprovisionamiento con Dockerfile y valores predeterminados.
  • Esquema JSON: autocompletado y validación en el editor para holos.yaml.
  • Ejemplos: stacks ejecutables y de plantilla con explicaciones al estilo README.
  • Funciones faltantes: carencias priorizadas que encajan con el objetivo de compose KVM de un solo host de holos.
  • Desarrollo: compilación, pruebas, requisitos del host y proceso de publicación.
  • Política de seguridad: versiones compatibles y reporte privado.
  • Modelo de amenazas / endurecimiento: verificación de imágenes, permisos de estado, bloqueos y guía operativa.
  • Contribuir: compilación, pruebas, estilo y convenciones de PR.

Requisitos del host

  • Linux con /dev/kvm
  • qemu-system-x86_64
  • qemu-img
  • Uno de cloud-localds, genisoimage, mkisofs o xorriso
  • Firmware OVMF / edk2-ovmf para UEFI o PCI passthrough
  • ssh para holos exec y los healthchecks

Ejecuta holos doctor para comprobar el host.

Solución de problemas

Permission denied al abrir /dev/kvm

Comprueba id -nG y ls -l /dev/kvm. En hosts donde el dispositivo pertenece al grupo kvm, añade tu usuario con sudo usermod -aG kvm "$USER", luego cierra sesión y vuelve a conectarte. Las shells existentes conservan su antigua pertenencia a grupos. Ejecuta holos doctor de nuevo desde la nueva sesión.

SSH se reinicia en el primer arranque

kex_exchange_identification: read: Connection reset by peer normalmente significa que cloud-init todavía está regenerando las claves del host y reiniciando sshd. holos exec espera hasta 60s por defecto, pero los primeros arranques muy lentos pueden necesitar otro reintento o holos exec -w 5m <project>.

La consola muestra Login incorrect

La consola serie puede intentar el autologin antes de que cloud-init cree el usuario. Espera a que aparezca cloud-init ... finished en el registro de la consola y luego usa holos exec. Las imágenes cloud generalmente no incluyen una contraseña de consola, y holos no añade ninguna.

up falla en macOS

KVM es una característica del kernel de Linux. Los binarios de macOS son útiles para la autoría y los comandos sin conexión, pero holos up y holos run deben ejecutarse en un host Linux con KVM.

Fuera de alcance

holos no es Kubernetes. No intenta resolver clustering multi-host, migración en vivo, mallas de servicios, redes overlay, planificadores, CRDs ni quórum del plano de control.

El objetivo es hacer que KVM sea viable para stacks de un solo host sin importar la forma operativa de Kubernetes.

Licencia

Categorías