prole/docs/config-environments.md

Knoe configuration environments

Knoe treats $KNOE_CONF as an explicit set of deployment-specific configs.

Directory layout

Under $KNOE_CONF:

$KNOE_CONF/k3d.cfg                   -> base config (k3d / dev)
$KNOE_CONF/k3s.cfg                   -> base config (k3s / service)
$KNOE_CONF/gke.cfg                   -> base config (k8s / prod)
$KNOE_CONF/test.cfg                  -> base config (test, optional)

Legacy layouts are still recognized for compatibility:

$KNOE_CONF/knoe.cfg                 -> legacy entrypoint
$KNOE_CONF/<env>/knoe.cfg           -> legacy env base config

Activation (selecting the active environment)

• The active environment is inferred from CLUSTER_ENV, KNOE_MODE, or DEPLOYMENT_MODE.
• Resolution prefers named root files (k3d.cfg, k3s.cfg, gke.cfg) and only falls back to legacy knoe.cfg paths.
• Switching environments changes which named file is selected; it does not overwrite other environment configs.

If a legacy knoe.cfg regular file is detected, migration preserves it as knoe.cfg.legacy.<timestamp> and promotes content into the appropriate named file.

Override layering (deterministic merge)

• Named root configs (k3d.cfg, k3s.cfg, gke.cfg, test.cfg) are loaded directly.
• Legacy env-directory layout still supports layered *.cfg overrides in lexicographic filename order.

Later files override earlier values (last write wins).

Why this prevents accidental namespace drift

• k3d, k3s, and k8s/GKE are cleanly separated by dedicated config files.
• Mode/environment selection is explicit via deployment hints instead of mutable symlink state.
• Legacy configs remain readable during transition, reducing migration risk.