Torna agli aggiornamenti
New releaseAug 14, 2026

holos v0.6.2

Strumento dichiarativo di orchestrazione di VM KVM/QEMU utilizzando file compose YAML. Gestisce stack multi-VM con cloud-init, SSH, PCI passthrough e verifica delle immagini senza libvirt o XML.

Condividi
holos

Docker compose per KVM. Definisci stack multi-VM in un unico file YAML. Niente libvirt, niente XML, niente control plane distribuito.

Sito web e documentazione: https://zeroecco.github.io/holos/

La primitiva è una VM, non un container. Ogni istanza di workload ottiene il proprio confine del kernel, overlay qcow2, seed cloud-init e accesso SSH generato.

Inizia da qui

Esegui le VM su un host Linux con /dev/kvm, QEMU e un builder di seed cloud-init. Vedi requisiti dell'host. Le build per macOS supportano l'authoring, il download delle immagini e la validazione; non possono eseguire VM KVM.

Installazione

I binari precompilati sono allegati a ogni release GitHub:

Questo esempio installa la build Linux x86-64. Utilizza curl, tar, sha256sum e la GitHub CLI (gh) per la verifica della provenienza. Per altre piattaforme, scegli l'archivio corrispondente nella pagina della release.

(
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
)

Le pagine di rilascio includono checksum SHA-256 e attestazioni degli artefatti GitHub per la provenienza firmata. Verifica entrambi prima di installare i binari sugli host di produzione.

Oppure, da un checkout di questo repository con Go 1.26 installato, compila dal sorgente:

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

Prova una VM

Usa un nome fisso in modo che ogni comando seguente funzioni così com'è scritto:

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

Ora sei nel guest. Esegui cat /etc/os-release, poi exit per tornare all'host. Dall'host:

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

Esci di nuovo dalla guest, poi rimuovi la VM usa e getta:

holos down try-holos   # deletes its guest disk

Eseguire un servizio web

Crea una directory vuota e salva questo come 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

Da quella directory:

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

Attendi hello from holos. L'attesa è importante: up avvia la VM, ma nginx viene installato durante il primo avvio. Se il provisioning fallisce, leggi holos logs web.

Uso quotidiano

All'interno di una directory di progetto:

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 nome di istanza come web-0 quando un servizio ha più repliche. Le modifiche che sostituiscono o rimuovono una VM richiedono holos up --recreate; controlla prima l'anteprima perché la sostituzione elimina il disco root di quella VM. I volumi con nome sopravvivono. Consulta la guida all'aggiornamento prima di aggiornare progetti creati da una versione precedente.

Quando hai finito con questo stack usa e getta:

holos down hello

stop conserva i dischi dell'istanza. down li elimina; i volumi con nome restano finché non vengono rimossi esplicitamente. Consulta la guida CLI per snapshot, volumi, lock delle immagini e configurazione di systemd.

Documentazione

  • Sito web: pagina di presentazione e documentazione renderizzata.
  • Guida CLI: VM ad hoc, exec, installazione systemd, import virsh e doctor.
  • File Compose: servizi, volumi, healthcheck, networking, PCI passthrough, provisioning tramite Dockerfile e valori predefiniti.
  • JSON Schema: completamento e validazione nell'editor per holos.yaml.
  • Esempi: stack eseguibili e template con spiegazioni in stile README.
  • Funzionalità mancanti: lacune prioritizzate che si adattano all'obiettivo di holos di compose KVM su singolo host.
  • Sviluppo: build, test, requisiti dell'host e processo di rilascio.
  • Politica di sicurezza: versioni supportate e segnalazione privata.
  • Modello di minaccia / hardening: verifica delle immagini, permessi dello stato, lock e indicazioni operative.
  • Contribuire: build, test, stile e convenzioni per le PR.

Requisiti dell'host

  • Linux con /dev/kvm
  • qemu-system-x86_64
  • qemu-img
  • Uno tra cloud-localds, genisoimage, mkisofs o xorriso
  • Firmware OVMF / edk2-ovmf per UEFI o PCI passthrough
  • ssh per holos exec e gli healthcheck

Esegui holos doctor per verificare l'host.

Risoluzione dei problemi

Permission denied all'apertura di /dev/kvm

Controlla id -nG e ls -l /dev/kvm. Sugli host in cui il dispositivo appartiene al gruppo kvm, aggiungi il tuo utente con sudo usermod -aG kvm "$USER", poi esci e riconnettiti. Le shell esistenti mantengono la vecchia appartenenza ai gruppi. Esegui di nuovo holos doctor dalla nuova sessione.

SSH si resetta al primo avvio

kex_exchange_identification: read: Connection reset by peer di solito significa che cloud-init sta ancora rigenerando le chiavi host e riavviando sshd. holos exec attende fino a 60s per impostazione predefinita, ma i primi avvii molto lenti potrebbero richiedere un altro tentativo o holos exec -w 5m <project>.

La console mostra Login incorrect

La console seriale potrebbe tentare l'autologin prima che cloud-init crei l'utente. Attendi cloud-init ... finished nel log della console, poi usa holos exec. Le immagini cloud generalmente non includono una password per la console, e holos non ne aggiunge una.

up fallisce su macOS

KVM è una funzionalità del kernel Linux. I binari per macOS sono utili per la scrittura e per i comandi offline, ma holos up e holos run devono essere eseguiti su un host Linux con KVM.

Non-obiettivi

holos non è Kubernetes. Non cerca di risolvere clustering multi-host, migrazione live, service mesh, overlay network, scheduler, CRD o quorum del control plane.

L'obiettivo è rendere KVM utilizzabile per stack su singolo host senza importare la forma operativa di Kubernetes.

Licenza

Concesso in licenza secondo la Apache License, Version 2.0. Consulta NOTICE per l'attribuzione.

Categorie