Ship Configuration Changes With the Same Evidence as Code

Deliver configuration as immutable revisions

Configuration is executable behavior. Produce an immutable reviewed revision, validate schema and cross-field meaning, promote it through environments, and report which processes actually loaded it. Keep secrets in a distinct delivery path. The Twelve-Factor App: Config explains separating configuration from code.

Canary a timeout change through its real delivery path

A timeout increase starts with units and bounds, then reaches one canary cohort. ConfigMap volumes can update eventually while environment variables require restart, so the rollout must reflect the real consumption path and verify the prior revision reloads. Kubernetes ConfigMaps documents these consumption and update paths.

Promote immutable revisions

Build one signed or content-addressed configuration revision from reviewed input. Validate syntax, units, ranges, cross-field rules, and references before promotion. A timeout of 30 without a unit or a percentage outside zero to one should never reach a process. Record author, reason, source revision, environment, and cohort.

Canary the exact revision that will expand. Services should expose the revision they loaded, not merely the value stored in the control plane. ConfigMap projection, polling, and environment-variable restart have different delivery semantics, so readiness must check the consuming process.

Plan a real reversal

A rollback is safe only if the new value has not already started irreversible work. Disabling a migration flag cannot undo rows written under a new format. Mark those settings as forward-only and define compensation before rollout.

Test malformed config, partial fleet uptake, a stalled watcher, control-plane outage, and rollback to the preceding revision. Stop expansion when error, saturation, or business guardrails cross a stated threshold. Choose one high-impact setting and make its loaded revision visible in diagnostics; then rehearse promoting and restoring it without editing production by hand. Finally, verify rollback from a cold process as well as a warm one; startup defaults often differ from live-reload behavior.