zeroecco/holosStrumento 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.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/holos-lockup-dark.svg">
<img alt="holos" src="https://raw.githubusercontent.com/zeroecco/holos/HEAD/docs/holos-lockup-light.svg" width="340">
</picture>
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 kernel, overlay qcow2, seed cloud-init e accesso SSH generato.
## Avvio Rapido
> Richiede Linux + `/dev/kvm`. Le build per macOS eseguono comandi offline come
> `validate`, `import`, `images` e `pull`, ma `up` e `run` necessitano di un host
> KVM.
Una VM usa e getta, senza file compose:
```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```
Uno stack a servizio singolo che puoi interrogare con `curl`. Salva come `holos.yaml`:
```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
```
```bash
holos up
curl localhost:8080
holos down hello
```
Questa è una vera VM che avvia una cloud image, installa un pacchetto, scrive la configurazione
e inoltra una porta dell'host.
## Installazione
I binari precompilati sono allegati a ogni
[GitHub release](https://github.com/zeroecco/holos/releases):
```bash
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
```
Le pagine di release includono checksum SHA-256 e attestazioni degli artefatti GitHub per
provenienza firmata. Verifica entrambi prima di installare i binari su host di produzione.
Oppure compila dai sorgenti:
```bash
go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor
```
## CLI
```text
holos up [-f holos.yaml] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
avvia tutti i servizi
holos run [flags] <image> [-- cmd...] avvia una VM usa e getta
holos down <project> ferma e rimuove un progetto
holos ps [-f holos.yaml] elenca i progetti in esecuzione
holos start [-f holos.yaml] [svc] avvia un servizio fermo o tutti i servizi
holos stop [-f holos.yaml] [svc] ferma un servizio o tutti i servizi
holos console <project> [<inst>] collega la console seriale
holos exec <project> [<inst>] [-- cmd...]
accedi via SSH a un'istanza
holos logs <project> [<svc|inst>] mostra i log della console
holos inspect [-f holos.yaml] [project|instance]
ispeziona lo stato come JSON
holos validate [-f holos.yaml] valida il file compose (--capacity/--network)
holos pull <image> scarica una cloud image
holos verify <image>|--all verifica i checksum delle immagini in cache
holos images elenca le immagini disponibili
holos images lock -f holos.yaml [-o holos.images.lock]
scrive il lockfile delle immagini del progetto
holos snapshots {create|list|rm|restore|export} ... gestisce gli snapshot della root
holos volumes [-f holos.yaml] [--json]
elenca i volumi con nome
holos volumes rm <project> <volume> rimuove un volume con nome scollegato
holos volumes export <project> <volume> <path>
esporta un volume con nome scollegato
holos volumes snapshot <project> <volume> <snapshot>
crea uno snapshot di un volume con nome scollegato
holos volumes snapshots <project> <volume>
elenca gli snapshot dei volumi
holos volumes snapshot-rm <project> <volume> <snapshot>
rimuove uno snapshot di volume
holos volumes snapshot-restore <project> <volume> <snapshot>
ripristina uno snapshot di volume
holos volumes snapshot-export <project> <volume> <snapshot> <path>
esporta uno snapshot di volume
holos volumes resize [--shrink] <project> <volume> <size>
ridimensiona un volume con nome scollegato
holos devices [--gpu] elenca i dispositivi PCI e i gruppi IOMMU
holos completion <bash|zsh|fish> stampa lo script di completamento della shell
holos doctor [--json] verifica le dipendenze dell'host
holos install [-f holos.yaml] [--system] [--enable]
installa un'unità systemd
holos uninstall [-f holos.yaml] [--system]
rimuove l'unità systemd
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
converte VM virsh in holos.yaml
```
## Documentazione
- [Sito web](https://zeroecco.github.io/holos/): landing page e documentazione renderizzata.
- [Guida CLI](https://github.com/zeroecco/holos/blob/main/docs/cli.md): VM ad hoc, `exec`, installazione systemd, import virsh
e `doctor`.
- [File Compose](https://github.com/zeroecco/holos/blob/main/docs/compose.md): servizi, volumi, healthcheck,
networking, passthrough PCI, provisioning Dockerfile e valori predefiniti.
- [JSON Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): completamento ed validazione nell'editor per
`holos.yaml`.
- [Esempi](https://github.com/zeroecco/holos/blob/main/examples/README.md): stack eseguibili e template con
spiegazioni in stile README.
- [Funzionalità mancanti](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): lacune prioritizzate che si adattano
all'obiettivo di holos di compose KVM su singolo host.
- [Sviluppo](https://github.com/zeroecco/holos/blob/main/docs/development.md): build, test, requisiti dell'host e
processo di rilascio.
- [Politica di sicurezza](https://github.com/zeroecco/holos/blob/main/SECURITY.md): versioni supportate e segnalazione privata.
- [Modello di minaccia / hardening](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
verifica delle immagini, permessi di stato, lock e guida operativa.
- [Contribuire](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): build, test, stile e convenzioni per le PR.
## Esempi
Inizia con il piccolo esempio nginx:
```bash
holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx
```
La directory degli esempi include anche provisioning Dockerfile, passthrough GPU
e uno stack multi-servizio che mostra `depends_on`, configurazione generata e
repliche.
## 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 passthrough PCI
- `ssh` per `holos exec` e gli healthcheck
Esegui `holos doctor` per verificare l'host.
## Risoluzione dei Problemi
### 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 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 cloud image 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 l'autoraggio e
i comandi offline, ma `holos up` e `holos run` devono essere eseguiti su un host
Linux KVM.
## Non-Obiettivi
holos non è Kubernetes. Non cerca di risolvere clustering multi-host, live
migration, 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 sotto la [Apache License, Version 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). Vedi
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) per l'attribuzione.