Documentation
¶
Overview ¶
Package orchestrator owns the VM lifecycle CLIENT-SIDE: it resolves the per-call dependencies (store, SSH key, image), spawns the VM helper, creates the network and boots/waits/tears down members by driving that helper over the control protocol. Since ADR-0020 it runs in the client on BOTH platforms and links NO concrete hypervisor — its backend is the pure-Go remote proxy (internal/backend/remote); the real vz/cloud-hypervisor backend lives only behind the helper (internal/holder). The helper binary is the downloaded signed fleetbox-helper on darwin and a self-reexec of the client binary on linux.
The clustering-capability gate and the public ErrClustersUnsupported sentinel live in the root package, not here: a caller is expected to have checked SupportsClustering before adding a second member, so Cluster.Add boots unconditionally.
Index ¶
- func AddMember(ctx context.Context, sibling, name string, optFns ...opts.Option) error
- func Prune() error
- func StartClusterDetached(ctx context.Context, names []string, optFns ...opts.Option) error
- type Cluster
- type VM
- func (v *VM) CopyFrom(_ context.Context, guestPath, hostPath string) error
- func (v *VM) CopyTo(_ context.Context, hostPath, guestPath string) error
- func (v *VM) Destroy(ctx context.Context) error
- func (v *VM) IP() net.IP
- func (v *VM) Name() string
- func (v *VM) SSH(_ context.Context, cmd string) (string, error)
- func (v *VM) State() string
- func (v *VM) Stop(ctx context.Context) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddMember ¶ added in v0.2.0
AddMember boots a new member onto the LIVE helper already serving `sibling`, without spawning a new one — how a stopped node re-joins a running cluster's network instead of getting an isolated one of its own. It drives the live helper through the sibling's socket: createnetwork is idempotent (returns the existing subnet), then the member is reserved and booted on that network.
func Prune ¶
func Prune() error
Prune reclaims the inert host network state a helper leaves behind if it dies without running its teardown — on Linux, orphaned bridges, taps, nft firewall tables, and a left-on uplink forwarding flag. It spawns a short-lived helper that reconciles and exits, because reconcile needs CAP_NET_ADMIN (it programs netlink and nf_tables), which the Linux helper carries. On macOS the root's prune is a no-op and never calls this (vmnet owns its own state) — ADR-0013/0020/0025.
func StartClusterDetached ¶ added in v0.2.0
StartClusterDetached boots the named VMs as one interconnected cluster on a single detached helper that persists after this process exits (the CLI's `up`). It is all-or-nothing: on any member's failure it rolls back the members already started and releases the helper. On success the helper is left running and the members are addressed later by name (ls/ssh/down).
Rollback is disk-safe: a re-up of stopped members (which already have persisted disks) only stops them, while members this call created fresh are destroyed — never delete a disk that existed before this `up` (see Cluster.rollback).
Types ¶
type Cluster ¶
type Cluster struct {
// contains filtered or unexported fields
}
Cluster is a set of VMs sharing one helper-owned network, so every member reaches the others by IP — a vmnet SharedMode network on macOS, a Linux bridge on Linux (ADR-0008, ADR-0011). The shared network is a runtime object in the helper, tied to the Cluster's lifetime — never persisted. The helper is spawned lazily on the first Add (it needs the first member's name); later Adds reserve and boot on the same live helper.
func NewCluster ¶
NewCluster prepares a cluster client; no helper is spawned until the first Add (the helper is launched on the first member's name). Shared client prep (store, SSH key, image) runs once here and is reused for every Add. The helper is bound — reaped when the caller goes away — matching the library lifetime.
func NewClusterDetached ¶ added in v0.2.0
NewClusterDetached is NewCluster for the CLI: the helper is spawned detached so it persists after the command exits, and reconnect-by-name addresses members later (ls/ssh/down). Cluster.Close releases the persistent helper rather than reaping it.
func (*Cluster) Add ¶
Add boots an additional VM on the cluster's shared helper and registers it as a member. The first Add spawns the helper; later Adds reserve and boot on the same live network, so the new VM reaches every existing member by IP. The clustering-capability gate lives in the root package's Cluster.Add, which is expected to have rejected a second member on a non-clustering host before reaching here, so Add boots unconditionally.
type VM ¶
type VM struct {
// contains filtered or unexported fields
}
VM represents a running virtual machine driven by the orchestrator. Since ADR-0020 the orchestrator is a client: it owns the pure-Go prep and drives a helper over the control protocol via a remote-proxy backend, so VM.backend is a remote handle, not a hypervisor.
func Start ¶
Start creates and boots a new VM with the given name on its own one-member helper. If the VM already exists, the helper boots the existing VM. The helper is bound (reaped when the caller goes away).
func (*VM) CopyFrom ¶ added in v0.5.0
CopyFrom copies guestPath out of the guest to hostPath over SSH. Like SSH it dials the VM IP directly; the 30s bounds only the dial/handshake (the transfer itself is unbounded and ctx is not honored in v1, matching SSH).
func (*VM) CopyTo ¶ added in v0.5.0
CopyTo copies hostPath into the guest at guestPath over SSH. Like SSH it dials the VM IP directly; the 30s bounds only the dial/handshake (the transfer itself is unbounded and ctx is not honored in v1, matching SSH).
func (*VM) Destroy ¶
Destroy stops the VM and removes all its files. The backend's Stop polls the member's pidfile, so the VM is confirmed down before its store files are deleted (R6).
Source Files