61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# `ctrl/k8s` — the cluster, and what runs on it
|
|
|
|
Same layout as every other project here: a kind config, a kustomize `base/`,
|
|
and an `overlays/dev/` that patches it.
|
|
|
|
```
|
|
kind-config.yaml.tpl the cluster itself — nodes, ports
|
|
base/ the components, as plain manifests
|
|
overlays/dev/ how this rig differs from the base
|
|
```
|
|
|
|
## Why the cluster config is a template
|
|
|
|
Every other project checks in a literal `kind-config.yaml`, because there is
|
|
exactly one `unt` and one `nvi`. A rig is copied and renamed to make a second
|
|
environment, and both the cluster name and the host port block follow the
|
|
directory name — so a literal would make every copy collide on both.
|
|
|
|
`ctrl/cluster.sh` renders it with `sed`, substituting `${CLUSTER}`,
|
|
`${NODE_IMAGE}`, `${HTTP_PORT}` and `${HOST_WORKDIR}`. Not `envsubst`: that is
|
|
`gettext-base`, which a minimal Debian does not have, and Docker being the only
|
|
prerequisite is the one promise rig makes.
|
|
|
|
**To change the cluster, edit this file** — more nodes, other port mappings —
|
|
then `make cluster reset`: a kind config is fixed at creation, not re-applied.
|
|
`lib/config.sh` reads the node count back out of it, so nothing restates it.
|
|
|
|
A project that builds its own cluster through rig passes its own file as
|
|
`KIND_CONFIG=<path>`; it is rendered the same way.
|
|
|
|
## `base/` — replace these
|
|
|
|
**The two components in `base/` are examples, not the system.** They exist so
|
|
the real manifests have a shape to be written against.
|
|
|
|
The real ones are expected to be versioned **separately from the installer** —
|
|
they change on a different cadence, by different people, under different review.
|
|
Point `MANIFESTS_DIR` in `ctrl/.env` at their overlay and rig stops owning them:
|
|
|
|
```
|
|
MANIFESTS_DIR=../platform-manifests/overlays/dev
|
|
```
|
|
|
|
Until then it defaults to `ctrl/k8s/overlays/dev`.
|
|
|
|
### 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.
|