Documentation
¶
Overview ¶
Package microvm brings a fleet of Enterprise Linux virtual machines up and down on the developer's own machine, under plain qemu, and renders a ZarfCluster inventory pointing at them. It exists because the phases that route on OS family cannot be exercised against a container: pkg/phase/21_prepare_selinux.go gates on getenforce reporting Enforcing, which no container reports, and that phase is fatal on failure -- so the one branch that can stop an apply is the one branch never run. The firewalld backend, fapolicyd, the *-selinux RPM scriptlets and the kernel-module reboot are in the same position.
Nothing here needs root, a daemon, or anything installed beyond qemu and mtools, and nothing it does outlives Down: the host's own SELinux, firewall and kernel are never touched. See docs/dev/microvm.md for the developer-facing walkthrough and docs/agent/choice-microvm-backend.md for why qemu rather than Firecracker or libvirt.
Index ¶
- Constants
- func Down(fleet, runRoot string) error
- func Fetch(ctx context.Context, img image) (string, error)
- func FetchImages(ctx context.Context, ids ...string) (map[string]string, error)
- func ImageIDs() []string
- func Inventory(f Fleet) apicluster.Cluster
- func SSHCommand(ctx context.Context, fleet, runRoot, node string, command ...string) (*exec.Cmd, error)
- type Fleet
- type Node
- type PortForward
- type Spec
- type Status
Constants ¶
const DefaultImageID = "rocky"
DefaultImageID is the guest a fleet runs when nothing asks for another.
Variables ¶
This section is empty.
Functions ¶
func Down ¶
Down tears a fleet down and removes its state. It is not an error to tear down a fleet that is not running: that is the state Down is asked to reach.
func Fetch ¶
Fetch returns the path to the cached base image, downloading it first if it is not already there. The download is written to a sibling .part file and renamed only once the digest matches, so an interrupted fetch leaves nothing a later run would mistake for a complete image.
The cache lives outside the repository, under XDG_CACHE_HOME, because it is the one artifact here worth keeping across a clean checkout.
func FetchImages ¶
FetchImages downloads and verifies the named guests, returning where each was cached.
The ids are the exported half of the image registry: callers outside this package name a guest by string rather than holding the definition, so the pins stay in one file.
func ImageIDs ¶
func ImageIDs() []string
ImageIDs are the guests a fleet can be built from, sorted so the listing is stable.
func Inventory ¶
func Inventory(f Fleet) apicluster.Cluster
Inventory renders a ZarfCluster inventory for a fleet.
PrivateAddress and PrivateInterface are both set explicitly, which the bootloose equivalent does not do. They have to be: a node's default route is on the slirp management interface, so fact gathering would discover 10.0.2.15 -- the same address on every node, and reachable from none of them. Every phase that distributes peer addresses, which is the firewall and the hosts file, would then distribute addresses that do not work.
func SSHCommand ¶
func SSHCommand(ctx context.Context, fleet, runRoot, node string, command ...string) (*exec.Cmd, error)
SSHCommand is the ssh invocation that reaches a node, as a command ready to run with the caller's stdio attached.
Host key checking is off and the known-hosts file is /dev/null. These nodes generate a new host key on every bring-up, so a known-hosts entry is wrong by construction -- and writing one would put a key for 127.0.0.1 on a port the next fleet reuses into the developer's real known_hosts.
Types ¶
type Fleet ¶
type Fleet struct {
// Name is the fleet name.
Name string
// Dir is the fleet's state directory.
Dir string
// KeyPath is the private half of the key every node trusts for root.
KeyPath string
// Nodes are the fleet's nodes, controllers first.
Nodes []Node
// Distro is the engine the fleet was prepared for, which decides the forwards.
Distro string
}
Fleet is a brought-up fleet: where its state lives, how to reach it, and what is in it.
func Up ¶
Up brings a fleet up and returns it, with every node answering SSH and the inventory written. It refuses a fleet that is already up rather than adopting it, so that a bring-up always starts from a fresh overlay: a node carrying the state of a previous run is the one thing that makes a phase failure impossible to reason about.
func (Fleet) InventoryPath ¶
InventoryPath is where Up writes the fleet's ZarfCluster inventory.
type Node ¶
type Node struct {
// Name is the hostname, and the directory name under the fleet's run directory.
Name string
// Role is apicluster.RoleController or apicluster.RoleWorker. Infra nodes are workers:
// the engine has no third role.
Role string
// Profile is the profile the node selects. It matches Role for controllers and plain
// workers, and is infraProfile for infra nodes.
Profile string
// Index is the node's 1-based position in the fleet, across both roles.
Index int
// SSHPort is the loopback port on the host forwarded to this node's sshd.
SSHPort int
// PrivateAddress is this node's address on the fleet's layer 2 segment. It is written
// into the inventory explicitly rather than discovered, because the slirp interface is
// the one holding the default route: fact gathering would pick that, and every phase
// that distributes peer addresses would then distribute addresses no peer can reach.
PrivateAddress string
// MgmtMAC and LANMAC address the two interfaces. cloud-init matches on these.
MgmtMAC string
LANMAC string
// HostFwd holds any additional loopback forwards, beyond SSH, for this node.
HostFwd []PortForward
// Image is the id of the guest this node runs, and OSID the os-release ID it reports.
Image string
OSID string
}
Node is one virtual machine in a fleet. Every address, port and MAC on it is derived from the fleet name and the node index rather than assigned at bring-up, so that a second command -- Down, List, SSH -- recomputes exactly what Up used without reading any state.
type PortForward ¶
PortForward is one loopback-to-guest TCP forward on the management interface.
type Spec ¶
type Spec struct {
// Fleet names the fleet, which scopes its run directory, its addresses and its ports.
Fleet string
// Controllers and Workers are how many of each role to create.
Controllers int
Workers int
// UbuntuControllers and UbuntuWorkers are how many nodes run Ubuntu instead of Rocky.
//
// Opt in, both defaulting to zero: a Rocky-only fleet is what the package was built for,
// and it is what every existing caller gets without changing anything. Asking for Ubuntu
// nodes is how the family-routed branches a single-distribution fleet cannot reach -- the
// APT upload phase, the ufw backend, the Debian Configurer, and the SELinux and fapolicyd
// gates correctly doing nothing -- get exercised against a real kernel.
UbuntuControllers int
UbuntuWorkers int
// Infra is how many infra nodes to create: workers carrying a profile of their own, so
// that the node-role labelling and the per-profile concurrency are exercised against a
// profile that is not simply the role's name.
Infra int
// MemoryMiB and CPUs are per node.
MemoryMiB int
CPUs int
// DiskSize is the virtual size of each node's overlay, in qemu-img syntax.
DiskSize string
// Distro selects which engine API ports are forwarded from the leader to the host, so
// that kube-config works from the management node. Either k3s or rke2.
Distro string
// RunRoot is the directory fleet state is written under. Empty means build/microvm.
RunRoot string
}
Spec describes a fleet to bring up. The zero value is not usable; Normalize fills in the defaults and rejects what cannot be defaulted.