Best Practices
You've learned the concepts, written your first cell, and built a working fleet in Your First Fleet. This section is the now do it well layer: the opinionated, scar-tissue guidance that keeps a fleet model legible as it grows from one cell to a few hundred head of cattle.
When to read this
Read these pages after you have something working, not before. The first-five-minutes path — terrantula import-terraform then terrantula dashboard — deliberately skips every judgment call here so you can see your fleet on one screen fast. Come back once you're about to:
- Add a second entity type, cell, or relationship and want the boundaries to be right the first time.
- Wire your first real Action and need its PRs to survive code review.
- Onboard more than one tenant, team, or environment.
- Move from local mode to a self-hosted server other people will use.
If you're still in your first hour, finish Your First Fleet first.
How to read these pages
Each page is prescriptive, not exhaustive — it tells you what to do, what to avoid, and why, with the reference docs one click away for the full field list. The format throughout is the same:
Do the thing that scales. Don't do the thing that rots. Because here's the failure mode it prevents.
The advice is grounded in one idea from the cattle mindset: you are modeling a herd, not pets. Every recommendation optimizes for the population — countable, placeable, governable, cleanly torn down — over the convenience of any single entity.
The five pages
| Page | When it bites you if you skip it |
|---|---|
| Modeling entities & cells | Entity types that are too coarse or too fine; cells drawn around the wrong axis. |
| Relationship & cascade design | Teardown in the wrong order; a tenant that leaks infrastructure on churn. |
| Actions & PR hygiene | Action PRs your reviewers can't read and your CI can't safely apply. |
| Multi-tenancy & self-hosting | Tenant data bleeding across boundaries; an Action that quietly assumes a SaaS dependency. |
Two rules that override everything below
These come from Terrantula's strategic commitments. If any practice on these pages seemed to conflict with them, the rule wins:
terraform applyEvery change to real infrastructure flows through an Action, which opens a PR (or fires a run against a runner you already operate). Your CI applies on merge. No best practice here ever has Terrantula execute Terraform.
The graph reflects state derived from Terraform; it doesn't author it. You don't fix a model problem by editing entities in the UI — you fix it in the catalog YAML and the Terraform the catalog drives.
Start with: Modeling entities & cells →