Configuration & GitOps

Thalweg is configured by TOML, layered TOML < env < CLI, validated at startup so nonsensical combinations fail to load rather than failing at runtime.

TOML is the source of truth; K8s only carries it

Kubernetes-native config is YAML, and a ConfigMap is a map[string]string. Rather than translate TOML↔YAML (which forces byte-stable round-tripping and leaks type and comment fidelity), Thalweg never lets K8s interpret the config — it only carries it. There is nothing to convert, so GitOps diffs stay clean: a config change is a one-line TOML diff, not a re-rendered YAML tree.

Two delivery modes, file-mount is the default:

File-mount (default). The ConfigMap holds the TOML (and each transform SQL) verbatim under its own key, mounted as a volume so it lands as a real file at a known path. The app loads it exactly as it loads a local core.toml — the same pattern used for transform SQL files.

Pointer (option). The ConfigMap holds a reference — an object-store URL or a path — and the TOML is fetched at startup via the shared resource loader. This decouples config lifecycle from deployment lifecycle (change config without a redeploy) at the cost of a boot-time fetch dependency; if the target is unreachable at startup, the process fails fast rather than starting on stale or absent config.

One loader for config, contracts, and SQL

Config (pointer mode), ODCS contracts, and transform SQL all resolve through twg-resource-loader: one local | http | object-store abstraction with one set of caching, retry, and fail-fast semantics. A resource is loaded and validated at startup; remote resources may opt into a refresh interval.

Secret enumeration

config secrets reads a resolved config and lists the secret references it requires, in text, json, or names form. It exists so a GitOps pipeline (for example ArgoCD plus a secrets operator) can provision exactly what a deployment needs without hand-maintaining a parallel list. It is pure inspection — it reads config and reports; it never resolves secret values.

This is the one piece of v2-era ConfigMap tooling worth keeping: it has nothing to do with TOML↔YAML translation, so dropping the conversion machinery does not cost it.