Sites & environments

Planned design. TractorStack is in development. This page describes how it is designed to work; nothing here is available to install yet. See the roadmap for the status of each part.

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

Before anything is built, it helps to agree what the words mean. This page describes sites, environments and stacks in TractorStack: how they relate, how they map to repositories on your own GitLab server, and how a change moves from a test environment to production. The aim is that anyone on your team can look at a repository name and know which machines it touches.

Sites, environments and stacks in TractorStack

Term	What it means	Example
Site	A physical place with its own hardware and network	A plant, an office, a colocation rack
Environment	A complete, separate copy of the platform on a site	test, production
Stack	One group of services inside an environment, usually from a stack kit	data platform, monitoring, an application

A site holds one or more environments. An environment holds several stacks. A small company might have one site with just production; a manufacturer might have four plants, each with test and production.

One repository per environment

Each environment gets its own Git repository on your self-hosted GitLab. That repository describes everything in the environment: the VMs and networks, the OS settings, the data services and the application stacks. A planned layout, as an illustration only:

# Planned example only
plant-a-prod/
  tofu/        VMs, disks, networks
  ansible/     OS, data services, Kubernetes install, checks
  compose/     stacks for stages 1 and 2
  k8s/         charts and Argo CD apps for stages 3 and 4
  runbooks/
  kits.yaml    which kits and versions this environment uses

Separate repositories give each environment its own history, its own approvers and its own site runner. A mistake in a test merge request can’t touch production, because production’s repository and credentials are elsewhere.

The infrastructure underneath is Proxmox VE first, or the infrastructure you already run. On Proxmox VE the tofu/ directory creates VMs, storage and networks. On vSphere or another hypervisor it manages what that platform exposes, and on bare-metal servers it may be nearly empty, with Ansible working directly on existing machines.

Naming

The design uses one pattern, <site>-<environment>, for repositories, GitLab groups, DNS zones and state schemas. So plant-a-prod is the repository, plant-a-prod.internal.example the zone and tofu_plant_a_prod the state schema. Names are short, lowercase and never reused for something else. Renaming a site later is possible but tedious, so it’s worth a few minutes of thought at the start.

Promotion from test to production

Test and production use the same kits. What differs is the version each one pins and the settings it supplies. A typical change goes like this:

A merge request in the test repository raises a kit version or changes a setting.
It goes through review and approval, is applied, and runs for an agreed time.
A matching merge request in the production repository makes the same change, linking to the test one.
Production’s approver checks that test ran cleanly, then approves.

Because production repeats a change already applied in test, rather than copying files across, the production plan is reviewed on its own merits. Differences in settings stay visible.

When there is no test environment

Many small sites only have production, and that’s fine for stage 1. The plan output and the dry run in the change request become the main safety check, and kit versions are only raised once they have run on other sites.

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