init rig

rig/ctrl/k8s/README.md

@@ -0,0 +1,71 @@
+# `ctrl/k8s` — cluster shape, and what runs on it
+
+Same layout as every other project here (`unt`, `nvi`, `eth`, `mpr`, and
+soleprint's generated rooms): a kind config, a kustomize `base/`, and an
+`overlays/dev/` that patches it. See ALL `projects/templates/conventions.md`.
+
+```
+kind-config*.yaml.tpl   the cluster itself — nodes, ports, audit
+base/                   the components, as plain manifests
+overlays/dev/           how this rig differs from the base
+audit-policy.yaml       mounted into the apiserver by the audit shapes
+```
+
+## 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.
+
+**The chosen file is the source of truth for node count and audit.**
+`lib/config.sh` reads both back out of it, so a profile names a shape and does
+not restate what the YAML already says.
+
+| file | nodes | audit | profiles |
+| --- | --- | --- | --- |
+| `kind-config.yaml.tpl` | 1 | off | `minimal`, `data` |
+| `kind-config.audit.yaml.tpl` | 1 | on | `offline` |
+| `kind-config.client.yaml.tpl` | 3 | on | `client` |
+
+A profile picks one with `KIND_CONFIG` in `ctrl/env.d/<profile>.env`. Adding a
+shape is adding a file — there is no dispatcher to edit.
+
+Audit is an apiserver flag and therefore fixed at creation: changing it is
+`make cluster reset`, not a re-apply.
+
+## `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.