
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.
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 edoctor. - 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_64qemu-img- Uno tra
cloud-localds,genisoimage,mkisofsoxorriso - Firmware OVMF / edk2-ovmf per UEFI o PCI passthrough
sshperholos exece 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.