vmrun

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: 36 Imported by: 0

Documentation

Overview

Package vmrun is factory-agent run's runtime inside a VM workspace (workspace-run.md). This file is its system setup: the environment that points every tool at the gateway (the proxies, the CA bundle, the placeholders) and, with --system-setup on, the privileged part (the system trust store, dockerd's proxy).

Index

Constants

View Source
const (
	CABundleFile = "ca-bundle.pem"
	DockerDir    = "docker"
)

The files Setup writes under the state dir.

View Source
const (
	// ExitOK: an outcome was written, whatever its status.
	ExitOK = 0
	// ExitUsage: the command line is wrong.
	ExitUsage = 2
	// ExitBundle: the run bundle is invalid; no event and no outcome.
	ExitBundle = 3
	// ExitOutcome: the outcome couldn't be written; the supervisor has only the events.
	ExitOutcome = 4
)

factory-agent run's exit codes (workspace-run.md §Exit codes and signals).

View Source
const (
	DefaultBundle   = "/var/lib/factory/run"
	DefaultWork     = "/work"
	DefaultStateDir = "/var/lib/factory-agent/run"
)

The flags' defaults. DefaultBundle is workspace.BundleDir, on the root disk: the bundle's skills hold executables and /run is a noexec tmpfs.

View Source
const (
	// DefaultDockerTimeout bounds the wait for dockerd after its restart.
	DefaultDockerTimeout = 60 * time.Second
)
View Source
const DefaultSudoGrace = 10 * time.Second

DefaultSudoGrace is ExecRunner's SudoGrace: setup's sudo -n commands (install, cat, mv, update-ca-certificates, systemctl, docker) end at once on the SIGTERM sudo relays, and SIGKILL after 10 s keeps a cancelled run well inside the 45 s the workspace driver's Exec gives it after SIGTERM, so it still writes its outcome.

View Source
const PlaywrightBrowsersPath = "/opt/ms-playwright"

PlaywrightBrowsersPath is where the base VM installs Playwright's Chromium (provision/base.sh's PLAYWRIGHT_BROWSERS). Setup exports it as PLAYWRIGHT_BROWSERS_PATH: Playwright's default, ~/.cache/ms-playwright, is under the pipeline's scratch HOME.

Variables

View Source
var DefaultNoProxy = []string{
	"localhost", "127.0.0.1", "::1", ".localhost",
	"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", ".svc", ".cluster.local",
}

DefaultNoProxy is what NO_PROXY always holds: the VM's own and the private addresses (the environment's services, a kind cluster's), before the manifest's Gateway.NoProxy.

Functions

func JobFromBundle

func JobFromBundle(b *runbundle.Bundle, now time.Time, remaining time.Duration) *runner.Job

JobFromBundle is the job the VM runs (workspace-run.md §Sequence, step 4): the lease rebuilt from the manifest and task.json, its git credentials holding GitAccess's metadata and empty tokens, no dispatcher client (API nil), no agent token, and the manifest's dispatcher. The pipeline refuses, in gateway mode, a job that carries any credential.

StartedAt is now + remaining − wall, where wall is the task's limits.maxWallClock (else pipeline.DefaultWallClock) and remaining, the supervisor's measure of what is left, is capped at wall (zero or less: the whole wall). The pipeline's deadline, StartedAt + wall, is then now + remaining, with no clock shared between the agent host and the VM. An invalid maxWallClock counts as the default here; the pipeline's Run refuses it.

func Main

func Main(ctx context.Context, args []string, stdout, stderr io.Writer) int

Main is `factory-agent run` (workspace-run.md §factory-agent run): it reads the run bundle, sets the VM up for the gateway, and runs the task's pipeline in the workspace with every credential outside the VM. stdout is the event stream (runbundle.Event lines) and stderr the log. It returns the exit code.

func ParseProxy

func ParseProxy(s string) (*url.URL, error)

ParseProxy parses --proxy: an absolute http URL with a host and a port and nothing else (no user info, path, query or fragment).

Types

type ExecRunner

type ExecRunner struct {
	// SudoGrace is how long a cancelled sudo call gets after SIGTERM before SIGKILL. Default:
	// DefaultSudoGrace.
	SudoGrace time.Duration
}

ExecRunner runs real programs, found on PATH.

func (ExecRunner) Run

func (r ExecRunner) Run(ctx context.Context, stdout, stderr io.Writer, name string, args ...string) error

Run implements Runner. When ctx ends, a sudo call gets SIGTERM, which sudo relays to its command (root, out of the run's reach), and SIGKILL only after SudoGrace; anything else gets SIGKILL (sudocancel.Apply).

type Runner

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

Runner runs a command, with its stdout and stderr (which may be the same writer).

type System

type System struct {
	// StateDir holds what the runtime writes outside the workspace (--state-dir): the CA
	// bundle and the docker client config. Required, absolute.
	StateDir string
	// WorkDir is the workspace root (--work, pipeline.Options.Root); "" skips it. Setup makes
	// it when it's absent, with sudo when its parent isn't writable by the run's user.
	WorkDir string
	// Root prefixes the system paths (/etc, /usr/local); "" is /.
	Root string
	// Runner runs sudo, install, cat, mv, update-ca-certificates, systemctl and docker;
	// default ExecRunner.
	Runner Runner
	// Clock times the wait for dockerd; default clock.Real.
	Clock clock.Clock
	// User is the run's user (its uid, gid and home); default user.Current.
	User func() (*user.User, error)
	// DockerTimeout bounds the wait for docker info; default DefaultDockerTimeout.
	DockerTimeout time.Duration
	// Logger gets the setup's progress; default slog.Default.
	Logger *slog.Logger
}

System is what Setup runs against. Tests replace the commands, the clock, the user and the file system root, so nothing privileged runs outside a VM.

func (System) Setup

func (s System) Setup(ctx context.Context, b *runbundle.Bundle, proxy *url.URL, mode SystemSetup) (map[string]string, error)

Setup prepares the VM for the run (workspace-run.md §System setup) and returns the environment that becomes pipeline.Options.Env and the environment runner's Env. The CA bundle and the docker client config are written in every mode; SetupOn also installs the gateway CA into the system store, gives dockerd the proxy and restarts it. Every error fails the run environment-error.

type SystemSetup

type SystemSetup string

SystemSetup is --system-setup: whether Setup runs its privileged part. There is no automatic mode: the supervisor, which knows it launched a workspace VM, passes SetupOn, and anything else gets the default, SetupOff, so a workstation or a CI runner with cached or passwordless sudo never has its trust store or dockerd changed by a guess.

const (
	// SetupOn installs the gateway CA into the system store and gives dockerd the proxy.
	SetupOn SystemSetup = "on"
	// SetupOff only builds the environment and the files under the state dir.
	SetupOff SystemSetup = "off"
	// DefaultSystemSetup is --system-setup's default.
	DefaultSystemSetup = SetupOff
)

func ParseSystemSetup

func ParseSystemSetup(s string) (SystemSetup, error)

ParseSystemSetup parses --system-setup: on or off.

Jump to

Keyboard shortcuts

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