6.8 KiB
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> addons, registry (OPTIONAL, examples ship as *.env.example)
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; the other twelve are unchanged.
default_cluster_name
The containing folder's name, reduced to something kind accepts as a cluster name (a DNS label: lowercase alphanumerics and dashes). Run from ctrl/, so the repo root is the parent.
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: identity follows the folder
Identity follows the FOLDER, so copying this directory 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.
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 for the reasoning.
load_config: MANIFESTS_DIR
Where the workload's manifests live, repo-root relative. Defaulted here so it is always resolved rather than sometimes-set: it is the seam that lets the real manifests be versioned away from the installer, and a consumer should not have to know whether anyone filled it in. See k8s/README.md.
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 must stay a host path even when this runs inside the installer container.
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.