lbdmod

package
v0.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
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"
)
View Source
const BuilderDockerfile = "Dockerfile"

BuilderDockerfile is the Dockerfile's name inside the build context, which BuildKit's dockerfile frontend takes as its "filename" attribute.

View Source
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`.

View Source
const DefaultDataPath = "/var/lib/miren"

DefaultDataPath is where miren keeps the lbd install record and build scratch space.

Variables

View Source
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

func Available(opts Options) bool

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

func BuilderImage(registryHost string) string

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

func IsBuilderImage(ref string) bool

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

func MaterializeBuilder(dir string) error

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

type BuildFailedError struct {
	ExitCode uint32
	Output   string
}

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.

func (Compiler) String

func (c Compiler) String() string

String renders the compiler for logs and error messages.

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

func DetectHost(root string) (Host, error)

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

func (h Host) CanFetchHeaders() bool

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

func (h Host) HeaderPackage() string

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

func (h Host) InstallHint() string

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

func (i *Installer) CheckHost(status Status) error

CheckHost refuses hosts that cannot build or load lbd before starting a container runtime.

func (*Installer) EnsureCurrent

func (i *Installer) EnsureCurrent(ctx context.Context) (bool, error)

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.

func (*Installer) Install

func (i *Installer) Install(ctx context.Context, force bool) (Status, error)

Install compiles the module against the running kernel and loads it. It is safe to call when the module is already installed and current: that is reported as a no-op unless force is set.

The caller must be root.

func (*Installer) Uninstall

func (i *Installer) Uninstall(ctx context.Context) error

Uninstall unloads the module and removes everything the install put on the host, including the record that would otherwise trigger a rebuild later.

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

func HostOptions(dataPath string) Options

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

func Probe(opts Options) (Status, error)

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

func (s Status) Available() bool

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.

func (Status) Explain

func (s Status) Explain() string

Explain renders the status as a sentence for logs and CLI output.

func (Status) Stale

func (s Status) Stale() bool

Stale reports whether this host installed the module before but what is on disk no longer fits -- almost always because the kernel was upgraded, but also when miren itself now carries a newer lbd. A usable old module is reported as stale but is not swapped out unattended.

Directories

Path Synopsis
Package ctrbuild runs the lbd builder image on containerd.
Package ctrbuild runs the lbd builder image on containerd.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL