katahelper

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package katahelper is the kata driver's root helper (design/workstreams/agent/LLD/ workspace-kata.md#the-helper-internalagentkatahelper), and the host layout it shares with host init's kata steps. The helper is a root-owned copy of factory-agent, installed by host init at HelperPath, that the owner runs with sudo -n; factory-agent's main runs Main when its argv[0]'s base name is Name.

It runs as root, so it trusts nothing from its environment: every path is a constant here, the commands it runs get an environment it builds itself (Env), and every argument is validated before anything runs. Its verbs take only workspace names, sizes, the image's tag, warm image references and fixed words; image-build reads its build context as a tar on stdin, never from a path.

Index

Constants

View Source
const (
	ExecFailed       = 125
	ExecFailedPrefix = Name + ": "
)

ExecFailed is exec's exit status for a failure of its own or nerdctl's, with ExecFailedPrefix starting its last stderr line; any other status is the remote command's.

View Source
const (
	// LibexecDir holds the helper and nerdctl-full.
	LibexecDir = "/usr/local/libexec/factory-agent"
	// HelperPath is the root-owned helper the sudoers rule allows.
	HelperPath = LibexecDir + "/" + Name
	// NerdctlFullDir is the extracted nerdctl-full release.
	NerdctlFullDir = LibexecDir + "/nerdctl-full"
	// Nerdctl is the pinned nerdctl.
	Nerdctl = NerdctlFullDir + "/bin/nerdctl"
	// CNIPluginDir holds nerdctl-full's CNI plugins.
	CNIPluginDir = NerdctlFullDir + "/libexec/cni"
	// KataDir is where Kata's static release unpacks (its configs name it).
	KataDir = "/opt/kata"
	// ConfigDir holds the rendered configs, the firewall and the CNI conflists.
	ConfigDir = "/etc/factory-agent"
	// CNIConfDir holds the workspaces' conflists.
	CNIConfDir = ConfigDir + "/cni/net.d"
	// StateDir is containerd's, nerdctl's, BuildKit's and CNI's state, and the workspaces' disks.
	StateDir = "/var/lib/factory-agent"
	// NerdctlDataRoot is nerdctl's own state.
	NerdctlDataRoot = StateDir + "/nerdctl"
	// RunDir holds the daemons' sockets.
	RunDir = "/run/factory-agent"
	// ContainerdSocket is the factory's containerd, apart from Docker's.
	ContainerdSocket = RunDir + "/containerd/containerd.sock"
	// BuildkitSocket is the factory's buildkitd.
	BuildkitSocket = RunDir + "/buildkit/buildkitd.sock"
	// Namespace is containerd's namespace for the workspaces and the image.
	Namespace = "factory"
	// NFTTable is the workspace firewall's table (inet), and NFTAllowSet its set of
	// (bridge, VM address, gateway address) elements, one per workspace.
	NFTTable    = "factory_workspaces"
	NFTAllowSet = "ws_allow"
	// BridgePrefix starts every workspace bridge's name: fws<slot>.
	BridgePrefix = "fws"
	// KataStateDir holds the workspaces' disks and slot files, and the warm disk.
	KataStateDir = StateDir + "/kata"
	// DisksDir holds each workspace's disk, <name>.img: its only mount, at GuestDisk.
	DisksDir = KataStateDir + "/disks"
	// SlotsDir holds a file per slot in use, named its number and holding the workspace's name.
	SlotsDir = KataStateDir + "/slots"
	// WarmDisk is the pre-filled disk create copies for a warm workspace.
	WarmDisk = KataStateDir + "/warm-docker.img"
	// BuildDir holds image-build's copies of the build contexts it receives, root-only.
	BuildDir = StateDir + "/build"
	// GuestDisk is where a workspace's disk file appears in it.
	GuestDisk = "/var/lib/factory/docker.img"
	// CNIStateDir is host-local IPAM's dataDir: a network's leases are in CNIStateDir/<network>.
	CNIStateDir = StateDir + "/cni"
	// LockFile is flocked around every slot allocation and release.
	LockFile = RunDir + "/kata.lock"
	// Slots is the number of workspace slots: slot n is 1 to Slots, its bridge BridgePrefix<n>.
	Slots = 63
	// ImageRepo is the workspace image's repository: its tag is factory-agent's version.
	ImageRepo = "factory-agent-base"
	// Runtime is Kata's containerd runtime (its runtime-rs shim, on Path).
	Runtime = "io.containerd.kata.v2"

	// The other programs the helper runs, by absolute path (Ubuntu's).
	IP       = "/usr/sbin/ip"
	NFT      = "/usr/sbin/nft"
	Sysctl   = "/usr/sbin/sysctl"
	CP       = "/usr/bin/cp"
	Truncate = "/usr/bin/truncate"
	Pkill    = "/usr/bin/pkill"

	// Path is the PATH of every command the helper runs, and of the daemons' units: Kata's
	// runtime-rs shim first, so containerd finds it for io.containerd.kata.v2.
	Path = KataDir + "/runtime-rs/bin:" + NerdctlFullDir + "/bin:/usr/sbin:/usr/bin:/sbin:/bin"
)

The host's layout (workspace-kata.md#host-layout): host init installs and renders these, and the helper's commands use them. They are constants, never flags or environment.

View Source
const ExecUser = "admin"

ExecUser runs every exec'd command: the image's admin (uid 1000, passwordless sudo), as tart exec's user, never the caller's choice. Anything that needs root goes through sudo -n.

View Source
const Name = "kata-helper"

Name is the helper's file name: factory-agent runs Main when invoked under it.

View Source
const Protocol = 7

Protocol is the helper's verbs' version: bump it whenever a verb's arguments or behaviour change. host check compares the installed helper's with this binary's, so a new factory-agent needs sudo again only when the helper changed.

2: create and rm, a workspace's slot, network, disk and container. 3: start, stop, inspect and exec. 4: exec runs as admin (3's ran as root). 5: image-build, image-exists and image-rm. 6: warm-load, warm-promote and warm-exists. 7: every verb stops on SIGTERM, SIGINT or SIGHUP, killing its command's process group, and image-build sweeps the build contexts a killed one left.

View Source
const Usage = "usage: kata-helper protocol | list | create <name> <cpus> <memMiB> <diskGiB> warm|empty <image> | start|stop|rm|inspect <name> | exec [-i] <name> <argv…>" +
	" | image-build <image> < context.tar | image-exists|image-rm <image> | warm-load <name> <ref> | warm-promote <name> | warm-exists"

Usage is the helper's usage line.

View Source
const WarmPlatform = "linux/amd64"

WarmPlatform is the only platform the workspaces run: warm-load pulls and saves it, and host init's warm disk step saves a kind image's archive for it alone.

Variables

View Source
var Env = []string{"PATH=" + Path, "HOME=/root", "NERDCTL_TOML=/dev/null"}

Env is the whole environment of the commands the helper runs: nothing comes from the caller's. NERDCTL_TOML names /dev/null, so no /etc/nerdctl/nerdctl.toml changes nerdctl's defaults.

View Source
var NerdctlGlobal = []string{
	"--address", ContainerdSocket, "--namespace", Namespace, "--data-root", NerdctlDataRoot,
	"--cni-path", CNIPluginDir, "--cni-netconfpath", CNIConfDir,
}

NerdctlGlobal are nerdctl's global flags for the factory's containerd, before every verb.

View Source
var SlotPool = netip.MustParsePrefix("10.213.0.0/16")

SlotPool is the workspaces' addresses (workspace-kata.md#the-workspace-network): slot n is 10.213.<n>.0/29, its bridge (the gateway) at .1 and its VM at .2.

Functions

func Main

func Main(args []string, stdin io.Reader, stdout, stderr io.Writer) int

Main runs one verb: kata-helper <verb> [args]. It returns the exit code: 0 on success, 2 for usage, 1 for any other failure (with one line on stderr); exec's are execVerb's.

A signal (sudo relays the caller's SIGTERM, a terminal's SIGINT or SIGHUP) ends the verb's context: its command's process group is killed and the verb removes what it made, rather than dying with nerdctl left running and an image-build's context copy left behind.

func Run

func Run(ctx context.Context, o Options, args []string) int

Run is Main with its options injected.

Types

type ExecRunner

type ExecRunner struct{}

ExecRunner runs real programs. A command leads its own process group, and when ctx ends the whole group is killed: nerdctl build's buildctl, say, dies with it. A command given the helper's own stdin (exec -i) stays in the helper's group instead, since its stdin may be a terminal, which a background group can't read; ctx's end kills only it.

func (ExecRunner) Run

func (ExecRunner) Run(ctx context.Context, env []string, stdin io.Reader, stdout, stderr io.Writer, name string, args ...string) error

Run implements Runner.

type Info

type Info struct {
	Slot    int        `json:"slot"`
	VM      netip.Addr `json:"vm"`
	Gateway netip.Addr `json:"gateway"`
	Running *bool      `json:"running,omitempty"`
}

Info is create's and inspect's output: the workspace's slot and addresses; inspect adds whether it runs.

type Options

type Options struct {
	Runner Runner
	// Root prefixes every path the helper reads or writes itself (its slot files, conflists,
	// lock, the disks it checks and removes, /sys): "" but in tests. The commands it runs get
	// the real paths.
	Root           string
	Stdin          io.Reader
	Stdout, Stderr io.Writer
	// Bound is rm's limit on each nerdctl stop and rm -f (60 s); KillWait its pause after
	// killing a hung workspace's processes (2 s).
	Bound, KillWait time.Duration
}

Options is what a verb runs with; Main's are the real ones.

type Runner

type Runner interface {
	Run(ctx context.Context, env []string, stdin io.Reader, stdout, stderr io.Writer, name string, args ...string) error
}

Runner runs a command with exactly env as its environment; stdin may be nil.

Jump to

Keyboard shortcuts

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