holos v0.6.2

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.

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 con KVM.

Una VM desechable, sin archivo compose:

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

Una pila de un solo servicio que puedes curl. Guárdala 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 de nube, instalando un paquete, escribiendo configuración y reenviando un puerto del host.

Uso diario

Dentro de un directorio de proyecto:

holos exec web       # open a guest shell
holos logs           # read project boot logs
holos stop web       # keep its disk
holos start web
holos up --dry-run   # preview configuration changes
holos help exec      # command syntax and options

Usa un nombre de instancia como web-0 cuando un servicio tenga múltiples réplicas.

Instalación

Los binarios precompilados se adjuntan a cada versión de GitHub:

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 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 compile desde el código fuente:

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

CLI

holos up [-f holos.yaml] [--dry-run] [--recreate] [--strict] [--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] [--strict]
                                     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 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 host único de holos.
Desarrollo: compilación, pruebas, requisitos del host y proceso de publicación.
Política de seguridad: versiones soportadas y reporte privado.
Modelo de amenazas / hardening: verificación de imágenes, permisos de estado, bloqueos 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, passthrough de GPU y una pila 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 passthrough de PCI
ssh para holos exec y las comprobaciones de estado

Ejecuta holos doctor para comprobar el host.