holos v0.6.3

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 cloud-init e acesso SSH gerado.

Início Rápido

Requer Linux + /dev/kvm. Builds para macOS executam comandos offline como validate, import, images e pull, mas up e run precisam de um host KVM.

Uma VM descartável, sem arquivo compose:

holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>

Um stack de serviço único que você pode acessar com curl. Salve 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

holos up
curl localhost:8080
holos down hello

Isso é uma VM real inicializando uma imagem cloud, instalando um pacote, escrevendo configuração e encaminhando uma porta do host.

Instalação

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

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

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

Ou compile a partir do código-fonte:

go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor

CLI

holos up [-f holos.yaml] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     inicia todos os serviços
holos run [flags] <image> [-- cmd...] inicia uma VM avulsa
holos down <project>                 para e remove um projeto
holos ps [-f holos.yaml]             lista projetos em execução
holos start [-f holos.yaml] [svc]    inicia um serviço parado ou todos os serviços
holos stop [-f holos.yaml] [svc]     para um serviço ou todos os serviços
holos console <project> [<inst>]     conecta ao console serial
holos exec <project> [<inst>] [-- cmd...]
                                     acessa uma instância via SSH
holos logs <project> [<svc|inst>]    mostra logs do console
holos inspect [-f holos.yaml] [project|instance]
                                     inspeciona o estado como JSON
holos validate [-f holos.yaml]       valida o arquivo compose (--capacity/--network)
holos pull <image>                   baixa uma imagem cloud
holos verify <image>|--all           verifica checksums de imagens em cache
holos images                         lista imagens disponíveis
holos images lock -f holos.yaml [-o holos.images.lock]
                                     escreve o lockfile de imagens do projeto
holos snapshots {create|list|rm|restore|export} ... gerencia snapshots de root
holos volumes [-f holos.yaml] [--json]
                                     lista volumes nomeados
holos volumes rm <project> <volume>  remove um volume nomeado desanexado
holos volumes export <project> <volume> <path>
                                     exporta um volume nomeado desanexado
holos volumes snapshot <project> <volume> <snapshot>
                                     cria snapshot de um volume nomeado desanexado
holos volumes snapshots <project> <volume>
                                     lista snapshots de volume
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove um snapshot de volume
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restaura um snapshot de volume
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     exporta um snapshot de volume
holos volumes resize [--shrink] <project> <volume> <size>
                                     redimensiona um volume nomeado desanexado
holos devices [--gpu]                lista dispositivos PCI e grupos IOMMU
holos completion <bash|zsh|fish>      imprime o script de autocompletar do shell
holos doctor [--json]                verifica dependências do host
holos install [-f holos.yaml] [--system] [--enable]
                                     instala uma unit systemd
holos uninstall [-f holos.yaml] [--system]
                                     remove a unit systemd
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     converte VMs virsh em holos.yaml

Documentação

Site: página inicial e documentação renderizada.
Guia da CLI: VMs avulsas, exec, instalação systemd, importação virsh e doctor.
Arquivo Compose: serviços, volumes, healthchecks, rede, passthrough PCI, provisionamento via Dockerfile e padrões.
JSON Schema: autocompletar e validação no editor para holos.yaml.
Exemplos: stacks executáveis e templates com explicações no estilo README.
Recursos ausentes: lacunas priorizadas que se encaixam no objetivo de compose KVM de host único do holos.
Desenvolvimento: build, testes, requisitos de 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, locks e orientações operacionais.
Contribuindo: build, testes, estilo e convenções de PR.

Exemplos

Comece com o pequeno exemplo nginx:

holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx

O diretório de exemplos também inclui provisionamento via Dockerfile, passthrough de GPU e um stack multi-serviço que demonstra depends_on, configuração gerada e réplicas.

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 PCI
ssh para holos exec e healthchecks

Execute holos doctor para verificar o host.

Solução de Problemas

SSH reinicia no primeiro boot

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

Console mostra `Login incorrect`

O console serial pode tentar autologin antes do 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 plano de controle.

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

Licença

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

Ler mais