cloudhypervisor

Documentation

Overview

Package cloudhypervisor implements the backend interface using cloud-hypervisor on Linux. It boots a stock cloud image with the pinned rust-hypervisor-firmware and controls the VM over cloud-hypervisor's REST API on a per-VM unix socket, using only the Go standard library — no cgo. It is the only package that knows cloud-hypervisor specifics (ADR-0002, ADR-0011).

Index

• type Backend
  • func New(binDir, netDir string) *Backend
  • func (b *Backend) Create(cfg backend.Config, nw backend.Network) (backend.VM, error)
  • func (b *Backend) CreateNetwork() (backend.Network, error)
  • func (b *Backend) NestedVirtSupported() bool
  • func (b *Backend) Reconcile() error
  • func (b *Backend) SupportsClustering() bool
• type VM
  • func (v *VM) Start(ctx context.Context) error
  • func (v *VM) State() backend.State
  • func (v *VM) Stop(ctx context.Context) error
  • func (v *VM) Wait(ctx context.Context) error
  • func (v *VM) WaitForIP(ctx context.Context) (string, error)

Types

type Backend

type Backend struct {
	// contains filtered or unexported fields
}

Backend implements the cloud-hypervisor backend.

func New

func New(binDir, netDir string) *Backend

New creates a cloud-hypervisor backend caching its binary and firmware under binDir and keeping network teardown records under netDir.

func (*Backend) Create

func (b *Backend) Create(cfg backend.Config, nw backend.Network) (backend.VM, error)

Create builds (but does not boot) a cloud-hypervisor VM attached to nw: it ensures the pinned binaries, checks /dev/kvm, and creates a tap enslaved to the cluster bridge. Boot happens in VM.Start.

func (*Backend) CreateNetwork

func (b *Backend) CreateNetwork() (backend.Network, error)

CreateNetwork creates a bridge on a free /24, assigns it the gateway address, and brings it up via netlink, then enables per-interface forwarding and installs the nft egress firewall. It first reconciles any network whose holder crashed (so orphans self-heal on every up), then write-ahead records the new bridge before creating it. The first netlink write (the bridge LinkAdd) doubles as the CAP_NET_ADMIN probe: without the capability it fails with EPERM and a clear error rather than a cryptic one deep in a later step (ADR-0025).

func (*Backend) NestedVirtSupported

func (b *Backend) NestedVirtSupported() bool

NestedVirtSupported reports whether /dev/kvm exists and KVM nested virtualization is enabled — what consumers running KVM inside guests need.

func (*Backend) Reconcile

func (b *Backend) Reconcile() error

Reconcile removes the host resources (bridges, taps, nft firewall tables) of every network whose owning holder is no longer alive, and restores the uplink's forwarding flag once nothing of ours remains. It is the engine behind `fleetbox prune`; the same sweep runs automatically at the start of each CreateNetwork so orphans from a crashed holder self-heal on the next up (ADR-0013, ADR-0025).

func (*Backend) SupportsClustering

func (b *Backend) SupportsClustering() bool

SupportsClustering is always true on Linux: cluster members share one bridge and reach each other (ADR-0011), unlike the macOS <26 NAT path.

type VM

type VM struct {
	// contains filtered or unexported fields
}

VM is a cloud-hypervisor virtual machine: a child process given its full configuration on the command line (so it boots on launch) and controlled afterwards over the REST API on its unix socket.

func (*VM) Start

func (v *VM) Start(ctx context.Context) error

Start launches cloud-hypervisor, which boots the VM immediately because the whole configuration is on the command line, then waits for the REST API to answer (confirming a live VM) or for the process to exit (a boot failure).

func (*VM) State

func (v *VM) State() backend.State

State reports the VM's current state (running until the process exits).

func (*VM) Stop

func (v *VM) Stop(ctx context.Context) error

Stop asks the guest to shut down over the REST API, escalating to SIGTERM then SIGKILL if it does not exit, and always removes the VM's tap and socket.

func (*VM) Wait

func (v *VM) Wait(ctx context.Context) error

Wait blocks until the cloud-hypervisor process exits or ctx is done.

func (*VM) WaitForIP

func (v *VM) WaitForIP(ctx context.Context) (string, error)

WaitForIP returns the statically assigned address once TCP port 22 on it is reachable. The address is known up front (allocated by the orchestrator), so this only confirms the guest's network is up.