Examples
Runnable, end-to-end demos of the cattle wedge — each one a real directory in the Terrantula repo you can clone and run. Every demo models the same scenario (a multi-tenant SaaS fleet placed onto capacity-bounded clusters) on a different substrate, so you can start from the one that matches the runner you already operate.
Across all of them the rules are the same: Terrantula computes placement and ordering,
Actions open pull requests against your IaC repo, and your existing runner applies
the change. Terrantula never runs terraform apply and never hosts your runner or state.
Filter by tag, then open an example for a fixed walkthrough — what you'll see → try it → key files → related docs → view on GitHub.
Bare Terraform + GitHub Actions (module per tenant)
Same boring-TF stack, stronger isolation: each tenant gets its own module and state file. The workflow applies only the changed tenant directory.
Bare Terraform + GitHub Actions (one file per tenant)
The default-shipping integration for the silent majority of Terraform shops. One file per tenant, for_each over a directory, apply from GitHub Actions.
Bare Terraform + GitLab CI (one file per tenant)
The GitLab CI sibling to the GitHub Actions demo. A pipeline-dispatch trigger writes the tenant file, runs the apply pipeline, and calls back to Terrantula.
Cattle: multi-stack greenfield (the golden path)
One command builds the cascade: four entities, three relationships, four Apply Actions in dependency order — each opening its own PR. The greenfield target shape.
Cattle: per-tenant SaaS (Atlantis)
The Atlantis-substrate variant. Terrantula opens a PR; the customer-hosted Atlantis plans and applies on comment. Module-per-tenant layout.
Cattle: per-tenant SaaS (Atmos)
The Atmos-substrate variant. Same blueprint; the Action invokes an Atmos workflow through a customer-deployed runner. Zero SaaS dependencies.
Cattle: per-tenant SaaS (Terraform Cloud)
The canonical demo. One command places a tenant onto the least-loaded cluster and fires a Terraform Cloud run. Substrate: TFC.
Reference runner: Atmos
The customer-deployed Docker runner for the Atmos-workflow trigger. Terrantula never hosts runners — you deploy this on your own infrastructure.
If you run terraform apply from a GitHub Actions workflow with state in S3 — the most
common stack — start with
Bare Terraform + GitHub Actions (one file per tenant).
If you're building a fresh IaC repo, the
multi-stack greenfield golden pathis the target shape.
The tags
| Tag | What it marks |
|---|---|
| Quickstart | The fastest on-ramps — a working graph view (and a first onboard) with minimal setup. |
| Substrate | Demonstrates a specific runner integration: Terraform Cloud, Atmos, Atlantis, or bare-TF + CI. |
| Modeling | Shows the catalog primitives — entity types, cells, relationships, and the cascade — in YAML. |
| Automation | Exercises Actions → pull requests → your runner: placement, lifecycle, and PR-driven change. |
| Self-host | Runs end-to-end with zero required SaaS dependencies — Terrantula + your CI + your state. |