60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# `examples/starter` — the overlay rig runs when you name none
|
|
|
|
An overlay is one folder, outside rig, that holds what runs: its settings, its
|
|
manifests, its images. rig reads it and never writes into it — see
|
|
[`docs/notes/overlay.md`](../../docs/notes/overlay.md) for the contract. This one
|
|
ships with rig so `make tilt` has something to deploy on a fresh clone, and so a
|
|
real overlay has a shape to be written against:
|
|
|
|
```
|
|
rig.env settings layered over rig's defaults (this one sets none)
|
|
k8s/base/ the components, as plain manifests
|
|
k8s/overlays/dev/ how this environment differs from the base — MANIFESTS_DIR's default
|
|
Tiltfile the workload's half of the dev loop; rig's ctrl/Tiltfile includes it
|
|
Dockerfile.example the shape of an image you build yourself
|
|
```
|
|
|
|
To start your own, copy this folder somewhere rig does not track —
|
|
`rig/local/<name>/`, or a repo of its own — and name it:
|
|
|
|
```bash
|
|
cp -r examples/starter local/myenv
|
|
OVERLAY=local/myenv make cluster up # or OVERLAY=local/myenv in ctrl/.env
|
|
```
|
|
|
|
The cluster, context and port block then follow the overlay's folder name
|
|
(`myenv`, `kind-myenv`), so it never collides with another.
|
|
|
|
## The two components are examples, not the system
|
|
|
|
They exist so the real manifests have a shape to be written against.
|
|
|
|
### The three states a component can be in
|
|
|
|
Switching between them should be a one-line change, never a rewrite. The DNS
|
|
name stays the same in every case, so callers never know the difference:
|
|
|
|
| state | what exists | when |
|
|
| --- | --- | --- |
|
|
| **real** | an image built from source, hot-reloaded | the one thing you are working on |
|
|
| **mock** | a stub returning canned responses (`example-mock.yaml`) | everything else — most of the estate |
|
|
| **remote** | no pod at all, just a Service (`example-remote.yaml`) | when the real system is reachable and you want it |
|
|
|
|
Most components should be **mock**. What has to be faithful is the topology —
|
|
names, ports, dependency order, who can reach whom, how it fails. The workloads
|
|
are noise, and mocking them is what makes several copies of a large estate fit
|
|
on one laptop.
|
|
|
|
## Images
|
|
|
|
`Dockerfile.example` is a commented shape, not a working build. Paths in this
|
|
folder's Tiltfile are relative to this folder, so `context='.'` is the overlay
|
|
and every `COPY` in the Dockerfile is relative to it:
|
|
|
|
```
|
|
docker_build(CLUSTER + '-api', context='.', dockerfile='Dockerfile.api')
|
|
```
|
|
|
|
The name given to `docker_build` must match `image:` in the manifest — that
|
|
string is the only thing connecting the two.
|