4.5 KiB
ctrl/.env.example, ctrl/env.d/*.env.example
ctrl/.env.example: header
Machine-local config. Copy to ctrl/.env (gitignored) and edit. The cluster SHAPE is an optional profile in ctrl/env.d/ — see the *.env.example there. The architecture MODEL lives in arch/.json — not in .env either.
ctrl/.env.example: CLUSTER
The kubectl context becomes kind-. LEAVE THIS UNSET unless you need a name that differs from the directory — it defaults to this folder's name, which is what makes the folder copyable: copy it, rename it, and you get a separate environment with no edits.
ctrl/.env.example: host ports
LEAVE UNSET — they derive from the directory name so several environments coexist without negotiating (see ctrl/ports.sh). make check shows this environment's block; bash ctrl/ports.sh persist writes it into ctrl/.env so it stops being derived and becomes fixed. Set a value only to override.
ctrl/.env.example: OVERLAY
The folder that holds what runs — its settings (rig.env), manifests, addons, Tiltfile — kept outside rig's version control: local/<name> (gitignored), or a repo of its own anywhere. Relative to rig's folder, or absolute. Unset, rig runs its own examples/starter. The cluster, context and port block follow the overlay's folder name. See overlay.md.
ctrl/.env.example: MANIFESTS_DIR
Where the manifests live. Leave it unset: the overlay's k8s/overlays/dev is the default. Set it only to point somewhere else, relative to rig's folder or absolute:
MANIFESTS_DIR=../platform-manifests/overlays/dev
Older copies of this file set MANIFESTS_DIR=ctrl/k8s/overlays/dev, rig's examples before they moved to examples/. That value is ignored while the folder does not exist, and make check says to delete the line.
ctrl/.env.example: DEPS_SOURCE
Where the installer fetches the pinned binaries from.
upstream— GitHub releases / dl.k8s.io (needs internet)artifactory— a generic repo; what a locked-down client usually allowsbaked— already inside the installer image; no network at all
ctrl/.env.example: registry secrets
The registry mode comes from the profile (REGISTRY_MODE). REGISTRY_REMOTE_URL, REGISTRY_USER and REGISTRY_PASSWORD are the secrets it needs, required for mirror/remote.
ctrl/.env.example: REGISTRY_CA_FILE
Corporate root CA, if Artifactory is fronted by an internal CA (it usually is). Trust has to reach THREE places and nothing does it for you: the host docker daemon, every kind node's containerd, and any in-cluster client. registry.sh handles the first two; check.sh reports when it's configured but not trusted. Symptom when missing: x509: certificate signed by unknown authority.
env.d/*.env.example: profiles in general
EXAMPLE PROFILES. rig needs none of these: with no profile it runs on its built-in defaults (lib/config.sh). To use one, copy it to .env in ctrl/env.d/ and name it — PROFILE= in ctrl/.env, or on the command line. It then overlays the defaults; anything it does not set, they still supply. An activated <name>.env is gitignored: it is this machine's choice.
A profile says how this machine reaches the world — a registry mirror, an air-gapped install. What runs is an overlay's business (overlay.md); its rig.env layers above the profile.
env.d/mirror.env.example
mirror — images through a pull-through cache of an internal registry, with TLS and metrics addons. More nodes or port mappings: edit the kind config (rig's, or the overlay's).
Real ports (80/443)
Ports derive from the directory name by default (see ctrl/ports.sh), so several environments run side by side.
Opt in to the real ports only when this is the ONLY environment and nothing else owns :80. They fail to bind otherwise, and docker reports it as an opaque "failed to bind host port 0.0.0.0:80/tcp: address already in use" halfway through cluster creation. make check checks before you spend the time. Uncommenting also means only one environment can exist at a time.
env.d/offline.env.example
offline — air-gapped. Everything comes from a local registry that was loaded ahead of time; nothing reaches the internet. Pair with the deps-full image (DEPS_SOURCE=baked) so the toolchain install is offline too, and so the manifests metallb and the other addons apply come from the image, verified, rather than from GitHub (see Dockerfile.deps.md). Their container images still have to be preloaded.
The heavier addons are left out to keep first boot viable.