111 lines
8.6 KiB
Markdown
111 lines
8.6 KiB
Markdown
# ctrl/lib/config.sh
|
|
|
|
## Purpose and precedence
|
|
|
|
The ecosystem convention is that scripts are standalone with no shared log library, and that still holds. This file is not a logging lib; it is the single definition of how the config layers compose, which every script has to agree on exactly. Precedence, weakest first:
|
|
|
|
```
|
|
built-in defaults in load_config; fill only what nothing else set
|
|
ctrl/versions.env pinned toolchain + image digests (committed)
|
|
ctrl/env.d/<profile> how this machine reaches the world (OPTIONAL, examples ship as *.env.example)
|
|
<overlay>/rig.env what runs: addons, namespaces, images (OPTIONAL, lives with the overlay)
|
|
ctrl/.env machine-local values and secrets (gitignored)
|
|
the caller's env `make cluster up PROFILE=<name>` (always wins)
|
|
```
|
|
|
|
That last rule is why this is more than a few `source` lines: .env sets PROFILE, so without snapshotting it would silently override the PROFILE the user just typed on the command line.
|
|
|
|
Run from ctrl/.
|
|
|
|
## CONFIG_OVERRIDABLE
|
|
|
|
Values a user can reasonably override per-invocation. Anything set in the environment when load_config runs is restored after the files are read. NODES is deliberately NOT here: it is read back out of the kind config, so the file is the one place that decides it.
|
|
|
|
REGISTRY_PORT and MANIFESTS_DIR were missing here while ctrl/.env set them, so the caller's env silently LOST to the file for those two, breaking the one precedence rule the header states. Both are now listed. OVERLAY joined with overlays, for the same reason: it is chosen per machine or per call.
|
|
|
|
## default_cluster_name
|
|
|
|
The environment's folder name — the overlay's when one is named, else rig's own — reduced to something kind accepts as a cluster name (a DNS label: lowercase alphanumerics and dashes). Run from ctrl/, so rig's folder is the parent.
|
|
|
|
## _from_ctrl, _abs_from_ctrl
|
|
|
|
Paths in the config are relative to rig's folder (MANIFESTS_DIR, OVERLAY) or to ctrl/ (KIND_CONFIG), or absolute. Scripts run from ctrl/, so `_from_ctrl` turns a rig-relative path into one usable from there, and `_abs_from_ctrl` into an absolute one for consumers outside bash (ports.sh active, the kind config's hostPath entries).
|
|
|
|
## derive_port_base
|
|
|
|
Base of this environment's 10-port block. cksum is used rather than $RANDOM or bash hashing because it is POSIX and returns the same value on every machine, which is what makes the block reproducible instead of merely unique.
|
|
|
|
## load_config: RIG_PORTABLE
|
|
|
|
RIG_PORTABLE skips the machine-local layer. config_snapshot sets it, so a generated standalone kit never carries this machine's .env, which holds local values and, by its own description, secrets.
|
|
|
|
## load_config: profiles are optional
|
|
|
|
A profile is an optional overlay, never a prerequisite. rig assumes no configuration: with no profile named, or no env.d/ at all, it runs on the built-in defaults. What IS an error is naming a profile that does not exist, because a typo must not quietly fall back to something else.
|
|
|
|
## load_config: overlays
|
|
|
|
An overlay is one folder, outside rig's version control, that holds what runs ([overlay.md](overlay.md)). `OVERLAY` names it; a named overlay that does not exist is an error, like a named profile. With none named, rig's own `examples/starter` is used if it is present — it sets nothing, so a plain rig resolves as it did before overlays — and a rig copied without `examples/` still resolves, with no manifests.
|
|
|
|
Its `rig.env` is layered after the profile and before ctrl/.env. It may not set PROFILE or OVERLAY, which are chosen before it loads, and the paths it sets are relative to the overlay (load_config rewrites them as it loads the file), so an overlay can be moved without editing it.
|
|
|
|
## load_config: identity follows the folder
|
|
|
|
Identity follows the FOLDER — the overlay's when one is named, else rig's — so copying either somewhere else and renaming it yields a distinct environment with no further edits. Without this, two copies would share one cluster and `make cluster down` in either would destroy the other's. It is also what lets a project carry rig at `<project>/rig/` without every such project's cluster being called `rig`.
|
|
|
|
## load_config: host ports
|
|
|
|
Host ports are a single shared namespace, so unlike the cluster name they cannot just follow the directory; they have to be spread out. Anything already set (ctrl/.env, a profile, the command line) wins; only the gaps are filled. See [ports.md](ports.md) for the reasoning.
|
|
|
|
## load_config: MANIFESTS_DIR
|
|
|
|
Where the workload's manifests live, relative to rig's folder or absolute: the overlay's `k8s/overlays/dev` unless something names another. It is the seam that lets the real manifests be versioned away from the installer. `none` means rig applies none (the overlay's Tiltfile does). A named folder that does not exist is an error; the old default `ctrl/k8s/overlays/dev`, pinned by older .env files, is ignored while that folder does not exist and reported by `make check`.
|
|
|
|
## load_config: NODE_MB
|
|
|
|
What one node costs, measured rather than guessed. On 2026-09-11 a minimal control-plane node ran at 620 MiB idle and ~728 MiB with a small mock, plus 16 MiB for the local registry: ~745 MiB of working set. 800 rounds that up, and agrees with the 800 MB observed independently on a larger rig. Worker nodes carry no etcd or apiserver and are lighter, so for a multi-node shape this errs high. It is the cluster alone: whatever you deploy comes on top.
|
|
|
|
It is set here rather than in check.sh because the memory tool and every standalone kit need the same figure.
|
|
|
|
## render_kind_config
|
|
|
|
Renders the kind config to stdout. sed rather than envsubst: envsubst is gettext-base, absent from a minimal Debian, and Docker is meant to be the only prerequisite. The variable list is explicit so a template cannot quietly start depending on something the caller does not set.
|
|
|
|
hostPath entries are resolved by the HOST dockerd, so HOST_WORKDIR and OVERLAY_DIR must stay host paths even when this runs inside the installer container. `${OVERLAY_DIR}` renders to the overlay's absolute path, for mounting its folders into the nodes.
|
|
|
|
## What a standalone kit needs to know
|
|
|
|
The kit generator (ctrl/standalone.sh) asks these questions so that it never has to know how configuration is stored. Where profiles live, which files are layered and what is derived are config.sh's business and can change freely; the generator only calls these functions.
|
|
|
|
## config_profiles
|
|
|
|
Every configuration rig can be run as, one per line: each profile file, or, when there are none, `default`, the built-in configuration load_config uses when no profile is named. Never empty, because rig never needs a profile.
|
|
|
|
## config_snapshot
|
|
|
|
The resolved configuration, as `declare -p` lines: exactly what load_config leaves behind, minus the machine-local layer. A kit freezes this in place of load_config, so it carries rig's decisions and not this machine's secrets.
|
|
|
|
```
|
|
config_snapshot <profile> that profile, as any machine would resolve it
|
|
config_snapshot --current what THIS machine runs: every overridable key as
|
|
resolved here, handed back in as if typed on the
|
|
command line, over the same portable resolution.
|
|
Values derived from those choices follow them;
|
|
anything else the local layer set (credentials)
|
|
is not carried. config_left_out names it.
|
|
```
|
|
|
|
Found by difference, not by a list: whatever load_config sets today, it sets. A list here would be one more place to forget a variable.
|
|
|
|
## config_left_out
|
|
|
|
What an export of this machine's configuration does NOT carry, by name only: keys the machine-local layer sets that are not choices a caller may override. They are this machine's own (registry and mirror credentials, mostly), so the target has to be told to supply them. Values are never printed.
|
|
|
|
## config_freeze
|
|
|
|
A replacement for load_config with a resolution frozen in (a profile, or --current; see config_snapshot), printed as a function definition for a standalone kit to carry. The generator embeds whatever this prints and interprets none of it, so what "frozen" means stays rig's decision.
|
|
|
|
It keeps load_config's one stated rule: the caller's env wins for anything in CONFIG_OVERRIDABLE. A kit therefore behaves like rig (`OUT_BIN=... rigdeps.sh` still works) rather than like a copy with everything pinned.
|
|
|
|
What freezing does give up, knowingly: values DERIVED from an overridable one are fixed at generation. Override CLUSTER and the ports stay the ones derived for the original name. Re-deriving would mean carrying the layering itself, which is exactly what a kit exists not to need.
|