Voltar às atualizações
New releaseAug 14, 2026

holos v0.6.2

Ferramenta declarativa de orquestração de VMs KVM/QEMU usando arquivos de composição YAML. Gerencia stacks de múltiplas VMs com cloud-init, SSH, PCI passthrough e verificação de imagens sem libvirt ou XML.

Compartilhar
holos

Docker compose para KVM. Defina stacks multi-VM em um único arquivo YAML. Sem libvirt, sem XML, sem plano de controle distribuído.

Site e documentação: https://zeroecco.github.io/holos/

A primitiva é uma VM, não um contêiner. Cada instância de workload recebe seu próprio limite de kernel, overlay qcow2, seed de cloud-init e acesso SSH gerado.

Comece aqui

Execute VMs em um host Linux com /dev/kvm, QEMU e um construtor de seed de cloud-init. Consulte requisitos do host. Builds para macOS suportam autoria, downloads de imagens e validação; eles não conseguem executar VMs KVM.

Instalação

Binários pré-compilados são anexados a cada GitHub release:

Este exemplo instala o build Linux x86-64. Ele usa curl, tar, sha256sum e o GitHub CLI (gh) para verificação de proveniência. Para outras plataformas, escolha o arquivo correspondente na página de releases.

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

As páginas de release incluem checksums SHA-256 e atestações de artefatos do GitHub para proveniência assinada. Verifique ambos antes de instalar binários em hosts de produção.

Ou, a partir de um checkout deste repositório com Go 1.26 instalado, compile a partir do código-fonte:

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

Experimente uma VM

Use um nome fixo para que todos os comandos abaixo funcionem como escritos:

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

Agora você está no guest. Execute cat /etc/os-release e depois exit para retornar ao host. A partir do host:

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

Saia do guest novamente e, em seguida, remova a VM descartável:

holos down try-holos   # deletes its guest disk

Executar um serviço web

Crie um diretório vazio e salve isto 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

A partir desse diretório:

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

Espere hello from holos. A espera é importante: up inicia a VM, mas o nginx é instalado durante o primeiro boot. Se o provisionamento falhar, leia holos logs web.

Uso diário

Dentro de um diretório de projeto:

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

Use um nome de instância como web-0 quando um serviço tiver múltiplas réplicas. Alterações que substituem ou removem uma VM exigem holos up --recreate; verifique primeiro a pré-visualização, pois a substituição exclui o disco raiz dessa VM. Volumes nomeados sobrevivem. Consulte o guia de atualização antes de atualizar projetos criados por uma versão mais antiga.

Quando terminar com esta stack descartável:

holos down hello

stop preserva os discos da instância. down os exclui; volumes nomeados permanecem até serem removidos explicitamente. Consulte o guia da CLI para snapshots, volumes, bloqueios de imagem e configuração do systemd.

Documentação

  • Site: página inicial e documentação renderizada.
  • Guia da CLI: VMs ad hoc, exec, instalação via systemd, importação do virsh e doctor.
  • Arquivo Compose: serviços, volumes, healthchecks, rede, passthrough de PCI, provisionamento via Dockerfile e padrões.
  • JSON Schema: autocompletar e validação no editor para holos.yaml.
  • Exemplos: stacks executáveis e de template com explicações no estilo README.
  • Recursos ausentes: lacunas priorizadas que se encaixam no objetivo do holos de compose KVM em host único.
  • Desenvolvimento: build, testes, requisitos do host e processo de release.
  • Política de segurança: versões suportadas e relato privado.
  • Modelo de ameaças / hardening: verificação de imagens, permissões de estado, bloqueios e orientações operacionais.
  • Contribuição: build, testes, estilo e convenções de PR.

Requisitos do Host

  • Linux com /dev/kvm
  • qemu-system-x86_64
  • qemu-img
  • Um dos seguintes: cloud-localds, genisoimage, mkisofs ou xorriso
  • Firmware OVMF / edk2-ovmf para UEFI ou passthrough de PCI
  • ssh para holos exec e healthchecks

Execute holos doctor para verificar o host.

Solução de problemas

Permission denied ao abrir /dev/kvm

Verifique id -nG e ls -l /dev/kvm. Em hosts onde o dispositivo pertence ao grupo kvm, adicione seu usuário com sudo usermod -aG kvm "$USER", depois faça logout e reconecte. Shells existentes mantêm a associação de grupo antiga. Execute holos doctor novamente a partir da nova sessão.

SSH reinicia no primeiro boot

kex_exchange_identification: read: Connection reset by peer geralmente significa que o cloud-init ainda está regenerando as chaves do host e reiniciando o sshd. holos exec aguarda até 60s por padrão, mas primeiros boots muito lentos podem exigir outra tentativa ou holos exec -w 5m <project>.

O console mostra Login incorrect

O console serial pode tentar autologin antes de o cloud-init criar o usuário. Aguarde cloud-init ... finished no log do console e então use holos exec. Imagens cloud geralmente não vêm com senha de console, e o holos não adiciona uma.

up falha no macOS

KVM é um recurso do kernel Linux. Binários para macOS são úteis para autoria e comandos offline, mas holos up e holos run devem ser executados em um host Linux com KVM.

Não-objetivos

holos não é Kubernetes. Ele não tenta resolver clustering multi-host, migração ao vivo, service meshes, redes overlay, schedulers, CRDs ou quórum de control plane.

O objetivo é tornar o KVM viável para stacks em host único sem importar o formato operacional do Kubernetes.

Licença

Licenciado sob a Apache License, Version 2.0. Consulte NOTICE para atribuição.

Categorias