Documentation
¶
Index ¶
- Constants
- Variables
- func Available(opts Options) bool
- func BuilderImage(registryHost string) string
- func BuilderTag() string
- func BuilderVersion() string
- func EnsureControlDevice() error
- func IsBuilderImage(ref string) bool
- func MaterializeBuilder(dir string) error
- func SourceVersion() string
- type BuildFailedError
- type BuildSpec
- type Builder
- type Compiler
- type Host
- type Installer
- type Marker
- type Mount
- type Options
- type Status
Constants ¶
const ( // ModuleName is what the module is called once loaded, and the name // modprobe takes. ModuleName = "lbd" // ControlDevice is the misc device the module registers. Its presence is // the only trustworthy proof that the module is loaded and working -- // lbdctl being on PATH proves nothing. ControlDevice = "/dev/lbd-control" )
const BuilderDockerfile = "Dockerfile"
BuilderDockerfile is the Dockerfile's name inside the build context, which BuildKit's dockerfile frontend takes as its "filename" attribute.
const BuilderRepository = "miren-system/lbd-builder"
BuilderRepository is the repository half of the builder's image reference. The registry resolves manifests by tag alone and ignores this, so it is here to make the reference readable in logs and `ctr images ls`.
const DefaultDataPath = "/var/lib/miren"
DefaultDataPath is where miren keeps the lbd install record and build scratch space.
Variables ¶
var ErrBuildInProgress = errors.New("an lbd build is already running on this host")
ErrBuildInProgress is returned when another process is already building the module on this host.
Functions ¶
func Available ¶
Available reports whether accelerator mode can run right now: the module is loaded, its control device exists, and lbdctl is there to drive it.
This is the check that decides a disk's mode, so it deliberately does not read the install record and cannot fail -- unlike Probe, which is for explaining the situation to a person. lbdctl being on PATH is not enough on its own: miren installs lbdctl alongside the module, so a host that has the binary but no loaded module would otherwise be sent down the accelerator path and fail at attach time.
func BuilderImage ¶
BuilderImage is the full reference the coordinator pushes to and nodes pull from. registryHost is normally ocireg.Host.
func BuilderTag ¶
func BuilderTag() string
BuilderTag is the tag the image is pushed under.
The tag carries SystemArtifactPrefix because an artifact's entity name is the tag it was pushed under, and that name is the only thing artifact GC has to tell a system image apart from a genuinely orphaned one. Without the prefix the toolchain image is archived within the hour and its blobs deleted. The rest is a content hash, so the tag moves exactly when the toolchain does.
func BuilderVersion ¶
func BuilderVersion() string
BuilderVersion is a content hash of the toolchain definition, used as the image tag. Hashing the content rather than tagging by hand means the image is rebuilt exactly when the Dockerfile or its build script changes, and never otherwise.
func EnsureControlDevice ¶
func EnsureControlDevice() error
EnsureControlDevice creates the misc device node when /dev is a private tmpfs without udev. The module must already be loaded so sysfs can supply its assigned device number.
func IsBuilderImage ¶
IsBuilderImage reports whether a reference names a cluster lbd toolchain tag.
This is an authorization check rather than a convenience. A node asked to build runs whatever the image's entrypoint says and then loads the result into its own kernel as root. The registry resolves manifests by tag alone, so checking the repository without the tag prefix would also accept an app image under a forged repository name.
The content hash is deliberately not checked: a newer coordinator may publish a different version of the toolchain for this node to build with.
func MaterializeBuilder ¶
MaterializeBuilder writes the toolchain definition into dir, which then becomes the BuildKit context. It has to reach a real directory: fsutil.NewFS only takes a path, and the repo has no in-memory build context.
func SourceVersion ¶
func SourceVersion() string
SourceVersion reports the miren.dev/lbd version this binary carries.
Types ¶
type BuildFailedError ¶
BuildFailedError reports a builder container that ran but exited non-zero. It carries the tail of the build output, which is where the real explanation lives.
func (*BuildFailedError) Error ¶
func (e *BuildFailedError) Error() string
type BuildSpec ¶
type BuildSpec struct {
// Name is the container's id. It is fixed rather than random so a build
// killed before its own cleanup leaves something the next run can find.
Name string
// Image is the builder image reference.
Image string
// Args replaces the image's entrypoint arguments.
Args []string
// Env is added to the image's environment as "KEY=value" pairs.
Env []string
// Mounts are bind mounts into the container.
Mounts []Mount
// HostNetwork gives the builder the host's network and resolver. It is
// set only when the builder has to fetch kernel headers for itself; a
// build against a host's own headers needs no network at all.
HostNetwork bool
}
BuildSpec describes one run of the builder image.
type Builder ¶
type Builder interface {
// Build runs the container to completion and returns nil only if it
// exited zero. A non-zero exit should be reported as a BuildFailedError
// so the build output survives.
Build(ctx context.Context, spec BuildSpec) error
}
Builder runs the builder image once and waits for it to finish. It is an interface so this package stays free of container runtime dependencies -- components/diskio and controllers/disk import it only to ask whether lbd is available, and should not pull containerd along with them. The containerd implementation is pkg/lbdmod/ctrbuild.
type Compiler ¶
type Compiler struct {
// Name is "gcc" or "clang", or empty when /proc/version says something
// we do not recognize.
Name string
// Major is the compiler's major version, or 0 if it could not be read.
Major int
}
Compiler identifies what built the running kernel.
type Host ¶
type Host struct {
// KernelRelease is `uname -r`, e.g. "6.8.0-51-generic". A module built
// here only loads on this exact release.
KernelRelease string
// HeadersDir is the kernel build tree the module must compile against,
// or empty if the host does not have one installed.
HeadersDir string
// Compiler is the toolchain the running kernel was built with, as
// reported by /proc/version.
Compiler Compiler
// DistroID and DistroLike come from /etc/os-release: ID is the specific
// distribution ("ubuntu"), and DistroLike is its family ("debian"), which
// is what decides how to name a header package. Either may be empty.
DistroID string
DistroLike []string
}
Host describes the machine we are about to build a module for.
func DetectHost ¶
DetectHost inspects the machine miren is running on. root is the filesystem to read from, normally "/"; tests pass a fixture directory.
Missing kernel headers are not an error here: whether they can be fetched instead is the caller's decision.
func (Host) CanFetchHeaders ¶
CanFetchHeaders reports whether the builder can install kernel headers for itself rather than borrowing the host's.
The builder image is Debian-based, so it can only reach a Debian-family archive. On any other distribution the operator has to install the headers, which is what InstallHint tells them to do. Even on a Debian-family host the fetch can still come up empty -- a kernel that has aged out of the archive, or a Debian host whose package is not in the builder's Ubuntu sources -- and the builder reports that itself, naming the package it could not find.
func (Host) HeaderPackage ¶
HeaderPackage names the distro package that provides the build tree for this kernel, so an error message can tell the operator exactly what to install. Returns an empty string when the distribution is not one we recognize.
func (Host) InstallHint ¶
InstallHint is the sentence to show an operator whose host has no kernel build tree.
type Installer ¶
type Installer struct {
// Log receives progress and the builder container's output.
Log *slog.Logger
// Builder runs the builder image. Required for Install; Uninstall does
// not need it. pkg/lbdmod/ctrbuild provides the containerd one.
Builder Builder
// Options say where to read host state and keep the install record.
Options Options
// Image is the toolchain image to build in. Empty falls back to the
// cluster registry reference, which is where the coordinator publishes it.
Image string
}
Installer builds and installs the lbd kernel module on this host.
func (*Installer) CheckHost ¶
CheckHost refuses hosts that cannot build or load lbd before starting a container runtime.
func (*Installer) EnsureCurrent ¶
EnsureCurrent rebuilds an installed module when it is no longer usable. An older but working module is left alone: swapping it unattended after a miren upgrade could strand disks if the new module fails to load.
A host with no install record is left alone: it never opted into accelerator mode, so it should not pay for an unattended compile at startup. It reports whether it rebuilt.
type Marker ¶
type Marker struct {
// LbdVersion is the miren.dev/lbd version the source came from.
LbdVersion string `json:"lbd_version"`
// KernelRelease is the kernel the module was built for. A module built
// for one release will not load on another.
KernelRelease string `json:"kernel_release"`
// BuilderImage is the cluster image used for this install. Retaining the
// reference lets startup rebuild without asking the coordinator to publish
// the current binary's potentially newer toolchain tag first.
BuilderImage string `json:"builder_image,omitempty"`
// ModulePath is where the built module was installed.
ModulePath string `json:"module_path"`
// LbdctlPath is where the built lbdctl was installed.
LbdctlPath string `json:"lbdctl_path"`
// BuiltAt is when the build finished.
BuiltAt time.Time `json:"built_at"`
}
Marker is the record left behind by a successful install. Its presence means this host has opted into accelerator mode, which is what licenses miren to rebuild the module unattended after a kernel upgrade.
type Mount ¶
type Mount struct {
// Source is the path on the host.
Source string
// Destination is where it appears inside the builder.
Destination string
// ReadOnly keeps the builder from writing through the mount.
ReadOnly bool
}
Mount is a bind mount into the builder.
type Options ¶
type Options struct {
// Root is the filesystem to read, normally "" for "/". Tests point this
// at a fixture directory.
Root string
// DataPath is miren's data directory, holding the install record.
// Defaults to DefaultDataPath.
DataPath string
// SearchPath holds extra directories to look for lbdctl in, ahead of
// PATH. The server's release directory belongs here: it is prepended to
// containerd's PATH but not to miren's own.
SearchPath []string
}
Options say where to look. The zero value probes the real host with miren's default data directory.
func HostOptions ¶
HostOptions builds the options for inspecting this host. dataPath is where miren keeps its data; empty means DefaultDataPath.
Everything that decides whether a disk gets accelerator mode goes through here, because they all have to reach the same answer or a node picks a mode it cannot serve. They disagreed before: the CLI searched the release directory it resolved through $HOME while the disk controller searched only the system one, so a host with lbdctl under ~/.miren/release would have the CLI choose accelerator and the controller choose universal.
The rule is now the system release directory and PATH, for every caller. Nothing resolves a per-user location, since the CLI and the server run as different users and would resolve it differently.
type Status ¶
type Status struct {
// Host is the machine as detected.
Host Host
// Loaded is true when the module is in /proc/modules.
Loaded bool
// ControlDevicePresent is true when /dev/lbd-control exists. Together
// with Loaded this is the real availability test.
ControlDevicePresent bool
// ModuleInstalled is true when a built module exists for the running
// kernel, whether or not it is currently loaded.
ModuleInstalled bool
// LbdctlPath is where lbdctl was found, or empty.
LbdctlPath string
// Marker is the record of the last successful install, or nil if this
// host has never installed the module.
Marker *Marker
// EmbeddedVersion is the miren.dev/lbd version this binary carries.
EmbeddedVersion string
}
Status is what miren knows about lbd on this host.
func Probe ¶
Probe reports what miren knows about lbd on this host. It never modifies anything, so it is safe to call without root.
func (Status) Available ¶
Available reports whether accelerator mode can actually run right now: the module is loaded, its control device is there, and lbdctl exists to drive it.