Documentation
¶
Overview ¶
Package image handles cloud image download, verification, and conversion.
The catalog is an embedded JSON file (catalog.json) keyed by alias; each alias pins a dated upstream snapshot and, per GOARCH, a download URL plus the SHA256 fetch verifies before use. The snapshot is stamped into the cache filename (for both the source and the converted raw) so an upstream bump is a cache miss, not a stale hit — images are pinned the way the VMM binary is (ADR-0011, ADR-0019).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Aliases ¶ added in v0.6.2
Aliases returns the catalog's image aliases (e.g. "debian-12", "ubuntu-26.04") sorted lexically — the set of OS names fleetbox can boot out of the box. It is the programmatic source of truth for the VM-boot test matrix (ADR-0030), so a new catalog entry is covered without editing a hand-maintained list. A malformed embedded catalog surfaces as an error, exactly as it does for Ensure.
func CopyDisk ¶
CopyDisk copies the source disk image to the destination with the given size. If size is larger than the source, the file is extended (sparse).
func Ensure ¶
Ensure downloads and prepares an image, returning the path to the raw disk. If the image is already cached it returns immediately. If urlOrAlias is a known catalog alias (e.g. "debian-12") the per-GOARCH entry is used: the source is fetched under a snapshot-stamped name, SHA256-verified, and converted (when it is a qcow2/.img) to the snapshot-stamped raw name. A non-alias is treated as a literal URL — unverified, with a basename-derived cache name (the BYO escape hatch, unchanged).
Types ¶
type ArchImage ¶ added in v0.2.0
ArchImage is the per-architecture pinned download: the snapshot-stamped URL and the SHA256 fetch verifies the downloaded source against before it is cached.
type ImageInfo ¶
type ImageInfo struct {
Distro string `json:"distro"`
Version string `json:"version"`
Codename string `json:"codename,omitempty"`
Snapshot string `json:"snapshot"`
BumpedAt string `json:"bumped_at,omitempty"`
Arch map[string]ArchImage `json:"arch"`
}
ImageInfo describes a pinned cloud image: a dated upstream snapshot and, per GOARCH, the snapshot-stamped download URL plus the SHA256 fetch verifies before use. The arch keys (amd64/arm64) match Go's GOARCH, so one alias resolves to the right image on macOS Apple Silicon and on Linux amd64/arm64.
Distro/Version/Codename/BumpedAt are inputs for the contrib/catalog refresher (the only writer of Snapshot/Arch values) and are ignored at runtime: the library reads only Snapshot (for the cache filename) and Arch (URL + SHA256).
Source Files