rig
rig builds a disposable Kubernetes environment on your machine, so you can see how a system fits together without access to any of it. It is for onboarding and exploration, not a production replica.
Most services in it are not real. What has to be faithful is the topology: names, ports, dependency order, who can reach whom, and how it fails. That is what makes a whole estate fit on a laptop. A real 20-service platform does not fit once in 14 GB; stubs of about 30 MB each fit three times.
Under the hood it is a kind cluster, a local image registry and a Tilt dev loop, each with its own name and ports, so several environments run side by side. What runs on it is an overlay: a folder outside rig that holds one use case.
Using rig from a project
You don't need to read rig to use it. Get a release (rig-<version>.tar.gz, or a checkout at
the tag rig-<version>), extract it anywhere, and point the project at it (RIG_DIR). Then run
make check: it says what the machine still lacks and which command comes next. .version
names the release; a project records the one it was last run against. See
docs/notes/overlay.md.
Prerequisite
Docker. Nothing else: no curl, jq, python or apt repositories.
On Windows, rig runs inside WSL. Run wsl --install once, from an elevated shell, then reboot.
Work inside the Linux filesystem, not /mnt/c: file watching doesn't work there, and
make deps warns about it. Git Bash, MSYS and Cygwin don't work (no /proc, no docker socket).
| symptom | cause |
|---|---|
| "the virtual machine could not be started" | virtualization disabled in BIOS/UEFI |
| the command is not recognised | Windows build too old (needs 2004 or later) |
| the install starts, then nothing works | a reboot is still pending |
On a machine with nothing but Docker, BOOTSTRAP.md runs the toolchain through the installer container.
What it does
| command | does |
|---|---|
make docs |
serves the docs locally; works before anything is installed |
make check |
is this machine ready? memory, toolchain, cluster, the next command (check all for every detail) |
make deps |
installs the pinned toolchain (deps core on a managed machine) |
make cluster up |
the cluster, its registry and the configured addons (down, reset, list, free) |
make tilt |
the dev loop: rig's part, then the overlay's Tiltfile |
make selftest |
checks rig itself |
make help |
every target |
Every verb is a Makefile target calling one script in ctrl/. The aliases (kind-up,
tilt-up, …) call the same scripts.
Overlays
An overlay holds its settings (rig.env), its manifests (k8s/overlays/dev), its Tiltfile and
images, its addons, and its kind config if it needs one. rig reads it and never writes into it.
cp -r examples/starter local/myenv # local/ is ignored
OVERLAY=local/myenv make cluster up
OVERLAY=local/myenv make tilt
With no overlay named, rig runs examples/starter. examples/data adds
postgres, redis and airflow as plain manifests. A project can carry rig at ./rig, or keep it
anywhere and name it with RIG_DIR.
The cluster name, context, image tags and ports derive from the overlay folder's name (rig's own, with no overlay), so environments never collide, and one's teardown never touches another.
Configuration
Layers, weakest first: built-in defaults < ctrl/versions.env < the profile < the overlay's
rig.env < ctrl/.env < the command line. A profile (ctrl/env.d/) is optional and says how
this machine reaches the world: mirror (a pull-through cache) and offline (air-gapped) ship
as examples. The cluster itself is one kind template: the overlay's, or rig's one-node default.
rig's own addons make the cluster work: metallb (LoadBalancer addresses), cert-manager (a
local CA), metrics-server (kubectl top). A workload's database, cache or scheduler belongs to
its overlay. There is no ingress controller: services are reached through LoadBalancer
addresses, or through the overlay's own gateway on the environment's HTTP port.
Where things are
Makefile the verbs
.version this release: patch and minor steps are edits here; milestones get a tag
ctrl/ one script per verb; lib/config.sh (settings and layers); Tiltfile (rig's
half of the dev loop); k8s/kind-config.yaml.tpl; addons/; env.d/; versions.env
docs/ index.html (make docs); notes/, one per script: why the code is as it is
examples/ starter (the default overlay), data (postgres, redis, airflow)
standalone/ single-file kits generated from ctrl/ (make standalone); never edited by hand
tests/ the installer's host fixtures
BOOTSTRAP.md from a bare machine with only Docker
STALE.md assumptions withdrawn, each checked by selftest