Docs / Build your stack

Settings & variables

In design Being designed now, alongside stage 1. Everything below is the planned design.

Every environment needs values that differ from the next one: addresses, sizes, retention periods, version numbers. Configuration: settings and variables covers how TractorStack plans to hold those values, where defaults come from, how one site overrides them, and the line between what goes in Git and what goes into secrets management. The short version: settings live in the repository, secrets never do.

Configuration: settings and variables

A setting is a named value an environment supplies, such as postgres_version or backup_retention_days. Each stack kit declares the settings it accepts, their types and their defaults. The environment repository provides values for the ones it wants to change.

The design keeps one settings file per environment, so there is a single place to read when you want to know how a site is configured. A planned example, for illustration only:

# Planned example only: settings.yaml in plant-a-prod
site: plant-a
environment: prod
network:
  vlan_servers: 20
  dns_zone: plant-a-prod.internal.example
postgres:
  version: "17"
  backup_retention_days: 30
rustfs:
  data_disk_gb: 2000

Where a value comes from

When a run needs a value, it is planned to look in this order and use the first one it finds:

1. The environment’s settings file
2. Shared settings for the site, used by all environments on it (for example the NTP servers or the internal certificate authority)
3. The kit’s documented default

If none of these has a value and the kit has no default, the run stops before planning anything. A missing setting is reported by name, not discovered halfway through an apply.

Per-site overrides

Overrides are for real differences: a plant with older disks needs a smaller volume, a site with slow off-site links keeps backups longer. They should be rare and explained. The design asks for a short comment next to each override, and the plan output for a merge request shows which values come from overrides, so a reviewer can spot a site drifting away from its siblings.

What goes in Git and what goes in secrets

A setting can point at a secret by name, for example postgres_admin_secret: pg-admin, and the site runner fetches the value at run time. The value is never written into the repository or printed in job logs. How secrets are stored and rotated is covered in secrets and credentials.

Same names at every stage

Applications get their configuration from environment variables, with the same names in Docker Compose and Kubernetes. This is one of the Kubernetes-ready rules, and the settings file is where those values start. Moving a site to stage 3 changes how the values are delivered, not what they are called.

Last updated 25 October 2026 · Questions or corrections: sales@infratractor.com