100 lines
4.8 KiB
Markdown
100 lines
4.8 KiB
Markdown
# 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`](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](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.
|
|
|
|
```bash
|
|
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`](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
|
|
```
|