Documentation
¶
Index ¶
- Constants
- Variables
- func BluefinDDI(version string) string
- func BluefinNetbootUKI(version string) string
- func BluefinVersionCheck()
- func CachedReleases(osName string) []string
- func CleanupLegacyRegistry()
- func CompareVersions(a, b string) int
- func CoreOSDataDir(version string) string
- func CoreOSVersionCheck()
- func CurrentRelease(osName string) string
- func CurrentTarget(osName string) string
- func EffectiveTarget(host *hardware.Host) string
- func FlatcarDataDir(version string) string
- func FlatcarVersionCheck()
- func FleetHold(osName string) string
- func FleetTarget(osName string) string
- func HoldFleetTarget(osName, version string)
- func InvalidateStorage()
- func LastGood(osName string) string
- func LoadFlatcarDigest(ctx context.Context, base, filename string) (string, error)
- func LoadRemoteBluefinVersion(ctx context.Context) (string, error)
- func LoadRemoteCoreOSVersion(ctx context.Context, arch string) ([]byte, string, error)
- func LoadRemoteFlatcarVersion(ctx context.Context) (string, error)
- func MigrateReleaseLayout()
- func MissingBluefinArtifacts(dataDir string) []string
- func MissingCoreOSArtifacts(dataDir, version, arch string) []string
- func MissingFlatcarArtifacts(dataDir string) []string
- func MissingFlatcarArtifactsIn(dir string) []string
- func MissingSecureBootArtifacts(dataDir string) []string
- func OSTracked(osName string) bool
- func PreviousRelease(osName string) string
- func ReleaseCached(osName, version string) bool
- func ReleaseDir(osName, version string) string
- func RemoteCoreOSJSONURL() string
- func SecureBootBundleVersion() string
- func SecureBootReady() bool
- func SecureBootVersionCheck()
- func SerialRollout(osName string, on bool)
- func SetLastGood(osName, version string) error
- func StartScheduler(schedule string, extra ...Job) (gocron.Scheduler, error)
- func SweepStaleTemp()
- func UntrackedReason(osName string) string
- func ValidBluefinVersion(v string) bool
- func ValidateBluefinFlags() error
- func ValidateHostOS(host *hardware.Host) error
- func ValidateSecureBootFlags() error
- func ValidateTargetVersion(host *hardware.Host) error
- func VerifyLocalArtifacts()
- type BluefinManifest
- type BluefinSysext
- type Bytes
- type FlatcarCAInfo
- type Job
- type SecureBootFile
- type SecureBootManifest
- type Storage
- type StorageAsset
- type StorageAutopilot
- type StorageEntry
- type StorageHosts
- type StorageOS
- type StorageRelease
Constants ¶
const ( // BluefinSumsFile and BluefinSigFile are the release's checksum list and // its detached OpenPGP signature; the node's initrd fetches both next to // the netboot UKI and verifies the DDI with them. BluefinSumsFile = "SHA256SUMS" BluefinSigFile = "SHA256SUMS.gpg" // Sysext names as they appear in BluefinManifest.Sysexts. NVIDIA driver // flavours (hardware.IsNvidiaDriverFlavour) appear under their own // name, nvidia-open-<branch>. BluefinSysextZFS = "zfs" BluefinSysextKubeStellar = "kubestellar" BluefinSysextK0s = "k0s" BluefinSysextKubeadm = "kubeadm" BluefinSysextNvidiaContainerToolkit = "nvidia-container-toolkit" )
Release file names, from projectbluefin/server's elements/oci/bluefin-server-image.bst.
const ( OSFlatcar = "flatcar" OSCoreOS = "coreos" OSBluefin = "bluefin" CurrentLink = config.BluefinCurrentLink PreviousLink = config.BluefinPreviousLink LastGoodLink = "lastGood" )
Every OS keeps its releases in DataDir/<os>/<version>/ behind three relative symlinks: current (the fleet target), previous (the release current replaced, so hosts mid-boot can finish) and lastGood (the newest release the whole fleet was healthy on; P1 sets it to current once and the autopilot controller moves it). Pruning keeps those three plus everything else retentionReasons names (pins, holds, netboot releases, recent demotions).
const ( SyncSecureBoot = "secureboot" SyncFlatcarCA = "flatcar-ca" )
Names under which state.SyncErrors reports Secure Boot failures (the OS syncs use OSFlatcar, OSCoreOS and OSBluefin).
const ( AssetIPXE = "ipxe" AssetShim = "shim" AssetSyslinux = "syslinux" AssetGrub = "grub" AssetOther = "other" )
Asset kinds, by what the top-level file is for.
const ( RetainedCurrent = "current" RetainedPrevious = "previous" RetainedLastGood = "lastGood" RetainedPinned = "pinned" RetainedHeld = "held" RetainedNetboot = "netboot" RetainedDemoted = "demoted" RetainedNone = "-" )
Retention reasons of a release directory, in the order one is picked (see retentionReasons).
const LegacyRegistryDir = "registry"
LegacyRegistryDir is where the removed OCI image cache kept its blobs and manifests.
Variables ¶
var ReleaseOSes = []string{OSFlatcar, OSCoreOS, OSBluefin}
ReleaseOSes lists the operating systems with a release directory.
Functions ¶
func BluefinDDI ¶
func BluefinNetbootUKI ¶
BluefinNetbootUKI, BluefinDDI and the sysext helpers name the release files of version.
func BluefinVersionCheck ¶
func BluefinVersionCheck()
BluefinVersionCheck brings the served Bluefin Server release in line with --bluefinVersion or the newest release. Concurrent invocations are skipped and the version only advances once every file is on disk and verified.
func CachedReleases ¶
CachedReleases lists the release directories of osName, newest first.
func CleanupLegacyRegistry ¶
func CleanupLegacyRegistry()
CleanupLegacyRegistry removes DataDir/registry when the old OCI image cache left nothing but empty directories behind, and otherwise tells the operator once that whatever is in it is unused and can be deleted.
func CompareVersions ¶
CompareVersions orders two release versions as dotted numbers (newer is greater), the way CachedReleases sorts them.
func CoreOSDataDir ¶
CoreOSDataDir is the /data/ path prefix ("coreos/<version>") of the release a host boots, "" while no release is cached (the compatibility names at the top of DataDir then).
func CoreOSVersionCheck ¶
func CoreOSVersionCheck()
CoreOSVersionCheck downloads the channel's latest Fedora CoreOS PXE artifacts when they differ from the served version. Concurrent invocations are skipped.
func CurrentRelease ¶
CurrentRelease, PreviousRelease and LastGood are the versions the three links name, "" when unset.
func CurrentTarget ¶
CurrentTarget is the OS's current release regardless of any hold.
func EffectiveTarget ¶
EffectiveTarget is the release host boots: its targetVersion when set and still cached (a pruned one falls back with a warning), else the fleet target of its OS.
func FlatcarDataDir ¶
FlatcarDataDir is the /data/ path prefix ("flatcar/<version>/") of the release a host boots, "" while no release is cached (the compatibility names at the top of DataDir then).
func FlatcarVersionCheck ¶
func FlatcarVersionCheck()
FlatcarVersionCheck brings the served Flatcar release in line with the pin (if set) or the channel's latest version. Concurrent invocations are skipped.
func FleetHold ¶
FleetHold is the version FleetTarget is held at for osName, "" when not held (or the held release is no longer cached). Under SerialRollout it is lastGood while current differs from it.
func FleetTarget ¶
FleetTarget is the release hosts of osName boot unless their targetVersion says otherwise: the OS's current release, "" while none is cached, or the release the autopilot holds the fleet at (see HoldFleetTarget). Bluefin's current is the bluefin/current link itself, which is what /bluefin/<mac>/ served before targetVersion existed.
func HoldFleetTarget ¶
func HoldFleetTarget(osName, version string)
HoldFleetTarget pins the fleet target of osName at version (a cached release, typically lastGood) instead of current; "" releases the hold. The autopilot controller is the only caller: it holds after a failed rollout and while a Bluefin release is rolled canary-serially. The hold is not persisted here; the controller re-applies it from its own state.
func InvalidateStorage ¶
func InvalidateStorage()
InvalidateStorage drops the cached walk so the next GET /storage recomputes; the release links and prunes call it.
func LoadFlatcarDigest ¶
LoadFlatcarDigest fetches <base>/<filename>.DIGESTS and returns the lowercase hex SHA512 checksum it lists.
func LoadRemoteBluefinVersion ¶
LoadRemoteBluefinVersion asks the configured source for the newest release and records it in state.
func LoadRemoteCoreOSVersion ¶
LoadRemoteCoreOSVersion fetches the Fedora CoreOS streams JSON, records the release for arch in state and returns the raw body for checksum extraction.
func LoadRemoteFlatcarVersion ¶
LoadRemoteFlatcarVersion fetches the channel's current version.txt and records the version in state.
func MigrateReleaseLayout ¶
func MigrateReleaseLayout()
MigrateReleaseLayout brings a data directory from before the per-OS release directories to DataDir/<os>/<version>/ with current, previous and lastGood links: Flatcar's top-level kernel/initrd (plain files, or symlinks into flatcar/<version>/) and CoreOS's flat fedora-coreos-<version>-live-* files move into their release directory, the top-level names stay as symlinks into <os>/current, and every OS with a current release gets lastGood = current when it has none. It is idempotent and runs before state.Init reads the versions.
func MissingBluefinArtifacts ¶
MissingBluefinArtifacts lists the files named by bluefin/current/manifest.json that are absent from dataDir. It is nil when there is no manifest, and names the manifest itself when it is unreadable or from the retired installer-v* format, so the next check downloads a release afresh.
func MissingCoreOSArtifacts ¶
MissingCoreOSArtifacts lists the Fedora CoreOS live PXE files for version/arch absent from dataDir: neither in coreos/<version>/ nor under their top-level name.
func MissingFlatcarArtifacts ¶
MissingFlatcarArtifacts lists the served Flatcar PXE files absent from dataDir.
func MissingFlatcarArtifactsIn ¶
MissingFlatcarArtifactsIn lists the Flatcar PXE files absent from a release directory.
func MissingSecureBootArtifacts ¶
MissingSecureBootArtifacts lists the bundle members named by secureboot/current/manifest.json that are absent from dataDir. It is nil when there is no manifest.
func OSTracked ¶
OSTracked reports whether Booty follows releases of osName at all: false for Flatcar or CoreOS when its channel flag is config.ChannelNone. An untracked OS has no cached releases as far as every caller here is concerned, whatever is left in its directory.
func PreviousRelease ¶
func ReleaseCached ¶
ReleaseCached reports whether version of osName is on disk.
func ReleaseDir ¶
ReleaseDir is DataDir/<os>/<version>.
func RemoteCoreOSJSONURL ¶
func RemoteCoreOSJSONURL() string
func SecureBootBundleVersion ¶
func SecureBootBundleVersion() string
SecureBootBundleVersion names the bundle directory after every pinned upstream version, so changing any flag produces a new bundle.
func SecureBootReady ¶
func SecureBootReady() bool
SecureBootReady reports whether HTTP Boot clients can be served: the flag is on and the current bundle is complete.
func SecureBootVersionCheck ¶
func SecureBootVersionCheck()
SecureBootVersionCheck syncs the Secure Boot bundle for the configured versions and the Flatcar CA for the served Flatcar release. It does nothing unless --secureBoot is on, and concurrent runs are skipped.
func SerialRollout ¶
SerialRollout switches osName to the canary-serial policy: FleetTarget answers lastGood whenever current differs from it, from the instant a release lands and not only once the controller's next tick holds the fleet. Without it a host's update timer firing in that gap sees the new current and kured reboots a host the rollout had not picked (seen in the P5 QEMU run). The controller sets it under --autopilot=full.
func SetLastGood ¶
SetLastGood points DataDir/<os>/lastGood at version, which must be cached.
func StartScheduler ¶
StartScheduler runs the Flatcar, CoreOS and Bluefin checks, plus any extra jobs, on schedule. Every job is a singleton: a tick that arrives while the previous run is still executing is dropped.
func SweepStaleTemp ¶ added in v1.1.0
func SweepStaleTemp()
SweepStaleTemp removes "*.tmp" leftovers of interrupted writes from the data directory: every temp file in an OS tree whose update lock it can take (no sync is writing there), and elsewhere those untouched for staleTempAge. Call it at startup, before StartScheduler.
func UntrackedReason ¶
UntrackedReason explains why an untracked OS is refused.
func ValidBluefinVersion ¶
ValidBluefinVersion reports whether v is usable as a Bluefin release version (20260927.123, 2026.09.0, 0.42).
func ValidateBluefinFlags ¶
func ValidateBluefinFlags() error
ValidateBluefinFlags checks --bluefinVersion, --bluefinKeyring and --bluefinOCI at startup: a pin must be a plain version, the keyring must parse (signature checks fail closed) and the OCI reference must be a repository.
func ValidateHostOS ¶
ValidateHostOS refuses a host whose OS Booty does not track.
func ValidateSecureBootFlags ¶
func ValidateSecureBootFlags() error
ValidateSecureBootFlags rejects version strings that could not be part of a URL path or directory name, and the trusted-CA list.
func ValidateTargetVersion ¶
ValidateTargetVersion checks a host's targetVersion at registration: empty, or a cached release of the host's OS.
func VerifyLocalArtifacts ¶
func VerifyLocalArtifacts()
VerifyLocalArtifacts reconciles the recorded Flatcar/CoreOS/Bluefin versions with what is actually on disk. A release whose PXE files are incomplete is reset to 0.0.0 so the next version check re-downloads it instead of trusting the stale record; a partial CoreOS set is removed outright.
Types ¶
type BluefinManifest ¶
type BluefinManifest struct {
Version string `json:"version"`
NetbootUKI string `json:"netbootUKI"`
DDI string `json:"ddi"`
Sysexts map[string]BluefinSysext `json:"sysexts,omitempty"`
SHA256Sums map[string]string `json:"sha256sums"`
}
BluefinManifest is DataDir/bluefin/<version>/manifest.json: the files of the release Booty serves. SHA256Sums holds the SHA256SUMS entries of every file Booty downloaded (the sysexts under their .raw.zst names).
func BluefinManifestFor ¶
func BluefinManifestFor(version string) (BluefinManifest, bool)
BluefinManifestFor returns the manifest of a cached release by version, ok=false when it is not on disk.
func CachedBluefinManifests ¶
func CachedBluefinManifests() []BluefinManifest
CachedBluefinManifests lists the manifests of every cached release, newest first.
func CurrentBluefinManifest ¶
func CurrentBluefinManifest() (BluefinManifest, bool)
CurrentBluefinManifest returns the manifest of the served release, or ok=false when no release has been installed yet.
func LoadBluefinManifest ¶
func LoadBluefinManifest(dir string) (BluefinManifest, error)
LoadBluefinManifest reads manifest.json from dir.
func PreviousBluefinManifest ¶
func PreviousBluefinManifest() (BluefinManifest, bool)
PreviousBluefinManifest returns the manifest of the release the current one replaced, still served to hosts that booted it.
func (BluefinManifest) Files ¶
func (m BluefinManifest) Files() []string
Files lists the artifacts the manifest references.
type BluefinSysext ¶
BluefinSysext is one decompressed sysext image in a release directory; Sha256 is the digest of the decompressed .raw.
type FlatcarCAInfo ¶
type FlatcarCAInfo struct {
FlatcarVersion string `json:"flatcarVersion"`
Sha256 string `json:"sha256"`
Subject string `json:"subject"`
NotBefore string `json:"notBefore"`
NotAfter string `json:"notAfter"`
Source string `json:"source"`
}
FlatcarCAInfo is DataDir/secureboot/flatcar-ca.json: which Flatcar release the CA next to it was extracted from and its fingerprint.
func CurrentFlatcarCA ¶
func CurrentFlatcarCA() (FlatcarCAInfo, bool)
CurrentFlatcarCA reads flatcar-ca.json; ok=false when it does not exist.
type Job ¶
type Job struct {
Name string
Fn func()
}
Job is an extra periodic task run on the same cron schedule as the version checks.
type SecureBootFile ¶
type SecureBootFile struct {
Name string `json:"name"`
Sha256 string `json:"sha256"`
Source string `json:"source"`
}
SecureBootFile is one member of the bundle manifest.
type SecureBootManifest ¶
type SecureBootManifest struct {
BundleVersion string `json:"bundleVersion"`
IPXEShimVersion string `json:"ipxeShimVersion"`
IPXEVersion string `json:"ipxeVersion"`
FedoraShimVersion string `json:"fedoraShimVersion"`
FedoraGrubVersion string `json:"fedoraGrubVersion"`
Files []SecureBootFile `json:"files"`
}
SecureBootManifest is DataDir/secureboot/<bundle>/manifest.json.
func CurrentSecureBootManifest ¶
func CurrentSecureBootManifest() (SecureBootManifest, bool)
CurrentSecureBootManifest returns the manifest behind secureboot/current, or ok=false when no bundle has been installed yet.
func LoadSecureBootManifest ¶
func LoadSecureBootManifest(dir string) (SecureBootManifest, error)
LoadSecureBootManifest reads manifest.json from dir.
func (SecureBootManifest) FileNames ¶
func (m SecureBootManifest) FileNames() []string
FileNames lists the bundle members the manifest expects on disk.
type Storage ¶
type Storage struct {
DataDir string `json:"dataDir"`
Total Bytes `json:"total"`
Free Bytes `json:"free"`
Used Bytes `json:"used"`
OS map[string]StorageOS `json:"os"`
Assets []StorageAsset `json:"assets"`
Other []StorageEntry `json:"other"`
Autopilot StorageAutopilot `json:"autopilot"`
ComputedAt time.Time `json:"computedAt"`
}
Storage is GET /storage: what the data directory holds and why.
func CurrentStorage ¶
func CurrentStorage() Storage
CurrentStorage is the data directory's storage view: sizes from a walk recomputed at most every storageTTL, joined with the current links and hosts.
type StorageAsset ¶
type StorageAsset struct {
Name string `json:"name"`
Bytes int64 `json:"bytes"`
Modified time.Time `json:"modified"`
Kind string `json:"kind"`
}
StorageAsset is a top-level file under DataDir that belongs to no release: the iPXE binaries, Secure Boot shims, pins and version files.
type StorageAutopilot ¶
type StorageEntry ¶
StorageEntry is any other top-level directory (config, cluster, secureboot, a leftover registry) with its size.
type StorageHosts ¶
StorageHosts names the hosts that reference a release: those whose last update check reported it running and those pinned to it by targetVersion.
type StorageOS ¶
type StorageOS struct {
Tracked bool `json:"tracked"`
Channel string `json:"channel"`
Pin string `json:"pin"`
Source string `json:"source,omitempty"`
Bytes int64 `json:"bytes"`
Releases []StorageRelease `json:"releases"`
}
StorageOS is the per-OS block of GET /storage.
type StorageRelease ¶
type StorageRelease struct {
Version string `json:"version"`
Bytes int64 `json:"bytes"`
Files int `json:"files"`
Modified time.Time `json:"modified"`
Links []string `json:"links"`
Hosts StorageHosts `json:"hosts"`
Retained string `json:"retained"`
Cached bool `json:"cached"`
}
StorageRelease is one DataDir/<os>/<version>/ directory.