zeroecco/holosOutil déclaratif d'orchestration de VM KVM/QEMU utilisant des fichiers de composition YAML. Gère des piles multi-VM avec cloud-init, SSH, PCI passthrough et vérification d'image sans libvirt ni 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 pour KVM. Définissez des piles multi-VM dans un seul fichier YAML. Pas de libvirt, pas de
XML, pas de plan de contrôle distribué.
Site web et documentation : <https://zeroecco.github.io/holos/>
La primitive est une VM, pas un conteneur. Chaque instance de charge de travail dispose de sa propre
frontière de noyau, de son overlay qcow2, de sa graine cloud-init et de son accès SSH généré.
## Démarrage rapide
> Nécessite Linux + `/dev/kvm`. Les builds macOS exécutent les commandes hors ligne comme
> `validate`, `import`, `images` et `pull`, mais `up` et `run` nécessitent un hôte
> KVM.
Une VM jetable, sans fichier compose :
```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```
Une pile à service unique que vous pouvez `curl`. Enregistrez sous `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
```
C'est une vraie VM qui démarre une image cloud, installe un paquet, écrit la configuration
et redirige un port de l'hôte.
## Installation
Des binaires précompilés sont joints à chaque
[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
```
Les pages de release incluent les sommes de contrôle SHA-256 et les attestations d'artefacts GitHub pour
une provenance signée. Vérifiez les deux avant d'installer des binaires sur des hôtes de production.
Ou compilez depuis les sources :
```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]
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
```
## Documentation
- [Site web](https://zeroecco.github.io/holos/) : page d'accueil et documentation rendue.
- [Guide CLI](https://github.com/zeroecco/holos/blob/main/docs/cli.md) : VM ad hoc, `exec`, installation systemd, import virsh
et `doctor`.
- [Fichier Compose](https://github.com/zeroecco/holos/blob/main/docs/compose.md) : services, volumes, healthchecks,
réseau, passthrough PCI, provisioning Dockerfile et valeurs par défaut.
- [JSON Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json) : complétion et validation dans l'éditeur pour
`holos.yaml`.
- [Exemples](https://github.com/zeroecco/holos/blob/main/examples/README.md) : piles exécutables et modèles avec
explications de style README.
- [Fonctionnalités manquantes](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md) : lacunes priorisées qui correspondent
à l'objectif de compose KVM mono-hôte de holos.
- [Développement](https://github.com/zeroecco/holos/blob/main/docs/development.md) : build, tests, prérequis de l'hôte et
processus de release.
- [Politique de sécurité](https://github.com/zeroecco/holos/blob/main/SECURITY.md) : versions prises en charge et signalement privé.
- [Modèle de menace / durcissement](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md) :
vérification des images, permissions d'état, verrous et conseils opérationnels.
- [Contribution](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md) : build, tests, style et conventions de PR.
## Exemples
Commencez par le petit exemple nginx :
```bash
holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx
```
Le répertoire examples inclut également le provisioning Dockerfile, le passthrough GPU
et une pile multi-service qui montre `depends_on`, la configuration générée et
les replicas.
## Prérequis de l'hôte
- Linux avec `/dev/kvm`
- `qemu-system-x86_64`
- `qemu-img`
- L'un de `cloud-localds`, `genisoimage`, `mkisofs` ou `xorriso`
- Firmware OVMF / edk2-ovmf pour UEFI ou passthrough PCI
- `ssh` pour `holos exec` et les healthchecks
Exécutez `holos doctor` pour vérifier l'hôte.
## Dépannage
### SSH se réinitialise au premier démarrage
`kex_exchange_identification: read: Connection reset by peer` signifie généralement
que cloud-init est encore en train de régénérer les clés d'hôte et de redémarrer sshd. `holos exec`
attend jusqu'à 60s par défaut, mais les premiers démarrages très lents peuvent nécessiter une nouvelle tentative ou
`holos exec -w 5m <project>`.
### La console affiche `Login incorrect`
La console série peut tenter une connexion automatique avant que cloud-init ne crée l'utilisateur.
Attendez `cloud-init ... finished` dans le journal de la console, puis utilisez `holos exec`.
Les images cloud ne sont généralement pas livrées avec un mot de passe de console, et holos n'en
ajoute pas.
### `up` échoue sur macOS
KVM est une fonctionnalité du noyau Linux. Les binaires macOS sont utiles pour l'écriture et les
commandes hors ligne, mais `holos up` et `holos run` doivent s'exécuter sur un hôte
Linux KVM.
## Non-objectifs
holos n'est pas Kubernetes. Il ne cherche pas à résoudre le clustering multi-hôte, la migration
à chaud, les maillages de services, les réseaux overlay, les ordonnanceurs, les CRD ou le quorum
du plan de contrôle.
L'objectif est de rendre KVM exploitable pour des piles mono-hôte sans importer la
forme opérationnelle de Kubernetes.
## Licence
Sous licence [Apache License, Version 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). Voir
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) pour l'attribution.