Skip to main content

ADR-0002: Resolve configuration at upload time, in the API server

Status​

Accepted

Context​

Template merging (platform defaults → runtime → template → environment → project) has to happen somewhere: in the API at upload, or in the operator at reconcile.

Decision​

The API server resolves and validates configuration at upload and embeds the result in the Release (spec.config). The operator only decodes.

Consequences​

  • Releases are reproducible and auditable: templateVersions records exactly which documents produced the snapshot.
  • Publishing a new template never mutates running workloads; it takes effect on the next upload. No surprise fleet-wide rollouts.
  • Invalid configuration is rejected synchronously with a 400 and a human-readable reason — developers find out in CI, not by watching a CR stuck in Failed.
  • The operator needs no S3 access for deploys (only build jobs read S3), shrinking its blast radius.
  • Cost: fixing a bad template requires a re-upload rather than a silent re-reconcile. That trade is intentional — explicit over magic.