Configuration¶

A Statera configuration file is declarative YAML. It names a service, an environment, and the settings to apply.

Structure¶

service: billing-api        # required
environment: production     # required
extends: base.yaml          # optional overlay base

settings:
  log_level: info
  rate_limit: 240
  feature_flags:
    new_invoicing: true

Overlays¶

Keep shared defaults in a base file and override only what changes per environment. The extends key merges the base first, then applies the local settings on top.

# base.yaml
service: billing-api
settings:
  log_level: info
  rate_limit: 200

# production.yaml
extends: base.yaml
environment: production
settings:
  rate_limit: 240     # overrides the base value

Maps are merged key by key; scalars and lists are replaced wholesale.

Secrets¶

Never put secret values directly in a configuration file. Reference them instead:

settings:
  db_password: ${secret:billing/db_password}

Statera resolves ${secret:...} references against the configured secrets backend at apply time and never stores the plaintext in its history.

Warning

A file containing a literal secret is rejected by the validator unless you pass --allow-inline-secrets, which is strongly discouraged.

Validation¶

Every value is checked against the service schema before it is applied. Validate locally without rolling anything out:

statera validate production.yaml

Common checks:

unknown keys not present in the schema
values outside their declared range
type mismatches (string where a number is expected)
unresolved secret references

See the configuration schema for the full set of rules.