holos v0.6.3

Docker compose para KVM. Define stacks multi-VM en un solo 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.

Inicio Rápido

Requiere Linux + /dev/kvm. Las compilaciones para macOS ejecutan comandos sin conexión como validate, import, images y pull, pero up y run necesitan un host KVM.

Una VM desechable, sin archivo compose:

holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>

Un stack de un solo servicio que puedes curl. Guarda 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

holos up
curl localhost:8080
holos down hello

Eso es una VM real arrancando una imagen cloud, instalando un paquete, escribiendo configuración y reenviando un puerto del host.

Instalación

Los binarios precompilados se adjuntan a cada GitHub release:

TAG=v0.6.3
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -LO $BASE/$ASSET
curl -LO $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 release incluyen checksums SHA-256 y atestaciones de artefactos de GitHub para procedencia firmada. Verifica ambos antes de instalar binarios en hosts de producción.

O compila desde el código fuente:

go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor

CLI

holos up [-f holos.yaml] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     start all services
holos run [flags] <image> [-- cmd...] launch a one-off VM
holos down <project>                 stop and remove a project
holos ps [-f holos.yaml]             list running projects
holos start [-f holos.yaml] [svc]    start a stopped service or all services
holos stop [-f holos.yaml] [svc]     stop a service or all services
holos console <project> [<inst>]     attach serial console
holos exec <project> [<inst>] [-- cmd...]
                                     SSH into an instance
holos logs <project> [<svc|inst>]    show console logs
holos inspect [-f holos.yaml] [project|instance]
                                     inspect state as JSON
holos validate [-f holos.yaml]       validate compose file (--capacity/--network)
holos pull <image>                   pull a cloud image
holos verify <image>|--all           verify cached image checksums
holos images                         list available images
holos images lock -f holos.yaml [-o holos.images.lock]
                                     write project image lockfile
holos snapshots {create|list|rm|restore|export} ... manage root snapshots
holos volumes [-f holos.yaml] [--json]
                                     list named volumes
holos volumes rm <project> <volume>  remove a detached named volume
holos volumes export <project> <volume> <path>
                                     export a detached named volume
holos volumes snapshot <project> <volume> <snapshot>
                                     snapshot a detached named volume
holos volumes snapshots <project> <volume>
                                     list volume snapshots
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove a volume snapshot
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restore a volume snapshot
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     export a volume snapshot
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos completion <bash|zsh|fish>      print shell completion script
holos doctor [--json]                check host dependencies
holos install [-f holos.yaml] [--system] [--enable]
                                     install a systemd unit
holos uninstall [-f holos.yaml] [--system]
                                     remove the systemd unit
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     convert virsh VMs into holos.yaml

Documentación

Sitio web: página de inicio y documentación renderizada.
Guía de CLI: VMs ad hoc, exec, instalación con systemd, importación de virsh y doctor.
Archivo Compose: servicios, volúmenes, healthchecks, redes, PCI passthrough, aprovisionamiento con Dockerfile y valores predeterminados.
JSON Schema: autocompletado y validación en el editor para holos.yaml.
Ejemplos: stacks ejecutables y plantillas con explicaciones al estilo README.
Funciones faltantes: brechas 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 release.
Política de seguridad: versiones soportadas y reporte privado.
Modelo de amenazas / hardening: verificación de imágenes, permisos de estado, locks y guía operativa.
Contribuir: compilación, pruebas, estilo y convenciones de PR.

Ejemplos

Comienza con el pequeño ejemplo de nginx:

holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx

El directorio de ejemplos también incluye aprovisionamiento con Dockerfile, GPU passthrough y un stack multiservicio que muestra depends_on, configuración generada y réplicas.

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 healthchecks

Ejecuta holos doctor para verificar el host.

Solución de Problemas

SSH se reinicia en el primer arranque

kex_exchange_identification: read: Connection reset by peer generalmente 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 autologin antes de que cloud-init cree el usuario. Espera a cloud-init ... finished en el log de la consola, luego usa holos exec. Las imágenes cloud generalmente no incluyen una contraseña de consola, y holos no agrega una.

`up` falla en macOS

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

No Objetivos

holos no es Kubernetes. No intenta resolver clustering multi-host, migración en vivo, service meshes, redes overlay, schedulers, CRDs ni quórum de 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

Licenciado bajo la Apache License, Version 2.0. Consulta NOTICE para atribución.