vm

package
v0.8.22 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package vm runs microVMs on this node: the bridge they share, and one Firecracker process per instance.

Each VM runs in its own transient systemd unit (jokku-vm-<id>), not as a child of the jokku daemon, so restarting or updating jokku leaves apps running. The unit's output is the guest's serial console, so app logs land in the journal tagged with JOKKU_APP and JOKKU_PROCESS.

Index

Constants

View Source
const MaxVolumes = 16

MaxVolumes is how many volumes one instance can mount.

Variables

This section is empty.

Functions

func CheckTCP

func CheckTCP(addr string) bool

CheckTCP reports whether something accepts connections at addr.

func HostDNS

func HostDNS() []string

HostDNS returns the resolvers this host uses, skipping local stubs such as systemd-resolved's 127.0.0.53 that a VM cannot reach.

Types

type Host

type Host struct {
	DataDir string       // /var/lib/jokku
	Bridge  string       // jokku0
	Gateway netip.Prefix // this node's address and subnet, e.g. 10.210.1.1/24
	Cluster netip.Prefix // the whole cluster network, e.g. 10.210.0.0/16
}

Host manages the microVMs on this node.

func (*Host) Attached

func (h *Host) Attached(ctx context.Context) (map[string]bool, error)

Attached returns the volume disk images attached to VMs that are running.

func (*Host) Available

func (h *Host) Available() error

Available explains why this machine cannot run microVMs, or returns nil.

func (*Host) CheckTCP

func (h *Host) CheckTCP(addr string) bool

CheckTCP reports whether something accepts connections at addr.

func (*Host) CreateVolume

func (h *Host) CreateVolume(ctx context.Context, path string, sizeMB int) error

CreateVolume makes an empty ext4 disk image of sizeMB, sparse so only what is written uses space. Unlike the scratch disk it has a journal: a volume must survive the VM or the host stopping abruptly.

func (*Host) EnsureNetwork

func (h *Host) EnsureNetwork(ctx context.Context) error

EnsureNetwork creates the bridge VMs attach to, with NAT for outbound traffic. It is idempotent and runs at every daemon start.

func (*Host) GrowVolume

func (h *Host) GrowVolume(ctx context.Context, path string, sizeMB int) error

GrowVolume enlarges a volume's disk image and its filesystem. The image must not be attached to a VM.

func (*Host) Remove

func (h *Host) Remove(ctx context.Context, id string) error

Remove deletes a stopped instance's network device and files. Its volumes are kept.

func (*Host) Session

func (h *Host) Session(ctx context.Context, id string) (io.ReadWriteCloser, string, error)

Session connects to a running VM's guest agent, returning the connection and the token the guest expects.

func (*Host) Start

func (h *Host) Start(ctx context.Context, s Spec) error

Start boots an instance. A restarted instance keeps its writable layer, as a restarted container does.

func (*Host) Stop

func (h *Host) Stop(ctx context.Context, id string, grace time.Duration) error

Stop asks the guest to shut down (SIGTERM to the app) and waits up to grace before stopping the VM outright.

func (*Host) Units

func (h *Host) Units(ctx context.Context) (map[string]string, error)

Units returns the state of every VM unit on this node, keyed by instance ID: active, activating, deactivating, failed. Missing means not running.

func (*Host) Usage

func (h *Host) Usage(ctx context.Context, ids []string) (map[string]Usage, error)

Usage reads CPU time and memory for running VMs in one systemctl call.

Memory is the anonymous memory of the VM's unit, not its MemoryCurrent: that also counts the host's page cache for the VM's disks (every block it reads or writes passes through it), which can be well over the VM's size and is the host's to reclaim, not the VM's.

type NoVMs

type NoVMs struct {
	Reason  string       // why apps don't run here
	Device  string       // e.g. jokku0
	Address netip.Prefix // the mesh address, in its subnet
}

NoVMs is the runtime of a node that runs no microVMs: an edge, which only routes traffic. Its one job is the node's mesh address, which sits on a dummy interface (where a VM host has its bridge) as the source of its traffic over the mesh.

func (*NoVMs) Attached

func (n *NoVMs) Attached(context.Context) (map[string]bool, error)

func (*NoVMs) Available

func (n *NoVMs) Available() error

func (*NoVMs) CheckTCP

func (n *NoVMs) CheckTCP(string) bool

func (*NoVMs) CreateVolume

func (n *NoVMs) CreateVolume(context.Context, string, int) error

func (*NoVMs) EnsureNetwork

func (n *NoVMs) EnsureNetwork(ctx context.Context) error

func (*NoVMs) GrowVolume

func (n *NoVMs) GrowVolume(context.Context, string, int) error

func (*NoVMs) Remove

func (n *NoVMs) Remove(context.Context, string) error

func (*NoVMs) Session

func (*NoVMs) Start

func (n *NoVMs) Start(context.Context, Spec) error

func (*NoVMs) Stop

func (*NoVMs) Units

func (n *NoVMs) Units(context.Context) (map[string]string, error)

func (*NoVMs) Usage

func (n *NoVMs) Usage(context.Context, []string) (map[string]Usage, error)

type Spec

type Spec struct {
	ID       string
	App      string
	Process  string // web.1
	Artifact string // rootfs image
	IP       string
	CPUs     int
	MemoryMB int
	Volumes  []Volume
	Guest    guest.Config
}

Spec is everything needed to boot one instance.

type Usage

type Usage struct {
	CPUNanos uint64 // total CPU time used so far
	// MemoryBytes is the VM's memory: its RAM (at most its size, once the
	// guest has touched it all) and Firecracker's own.
	MemoryBytes uint64
}

Usage is a VM's resource use as systemd accounts it.

type Volume

type Volume struct {
	Disk string
	Path string
}

Volume is a disk image attached after the scratch disk (vdd, vde, ...) and mounted at Path in the guest.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL