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 ¶
const ( CABundleFile = "ca-bundle.pem" DockerDir = "docker" )
The files Setup writes under the state dir.
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).
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.
const ( // DefaultDockerTimeout bounds the wait for dockerd after its restart. DefaultDockerTimeout = 60 * time.Second )
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.
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 ¶
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 ¶
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 ¶
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.
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.