
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.
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 ydoctor. - 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_64qemu-img- Uno de
cloud-localds,genisoimage,mkisofsoxorriso - Firmware OVMF / edk2-ovmf para UEFI o PCI passthrough
sshparaholos execy 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.