Features
A scannable tour of what Terrantula gives you. Each capability links to where you learn it in depth.
Model the fleet
Entities
Typed, stateful records of what exists — a tenant, a cluster, a database. Each carries properties (typed fields like region or tier), states (a lifecycle: provisioning → active → draining), metrics (capacity values, pushed in or derived automatically), and constraints (hard limits enforced at creation, e.g. max 50 tenants per cluster).
Cells
Named groups of entities of a single type. Cells do two jobs: placement (rank members by a metric and surface the best candidate) and aggregate constraints (enforce ceilings across the whole group, e.g. no more than 500 tenants across the production fleet). Cells compose into hierarchies; membership is computed dynamically — no duplication, no sync risk.
Relationships
Typed, stateful, directional connections — "tenant X runs on cluster Y." A relationship type defines cardinality (one-to-one, one-to-many, many-to-one, many-to-many), states, properties on the connection itself, and constraints (oversubscription protection — the sum of allocated CPU across all relationships can't exceed cluster capacity).
→ Learn these in Core Concepts.
Orchestrate the fleet
Actions → pull requests
Declarative workflows triggered against entities. An Action validates parameters, evaluates conditions, enforces constraints, picks a cell, transitions the entity or relationship — and fires a trigger. The load-bearing trigger is the pull request: Terrantula opens a PR against your repo and your CI applies it. Terrantula never runs terraform apply.
The cascade
A change rarely touches one thing. Terrantula computes the ordered set of dependent transitions — the cascade — and surfaces it before anything happens, so you see the blast radius of onboarding or deprovisioning a tenant up front.
Audit trail
Every Action execution produces an ActionRun with a full record: parameters, placement selections, status, output, errors. Timeouts are reaper-enforced; transient delivery failures retry with backoff.
→ Learn these in Wire an Action and the Triggers reference.
Sit on top of any substrate
Terrantula integrates above the tool that runs your Terraform — it never hosts runners or state.
- Bare Terraform + GitHub Actions / GitLab CI + S3 state — the default-shipping integration; a reference workflow template Terrantula triggers via
repository_dispatch. - Terraform Cloud / HCP Terraform — fires a run and tracks completion.
- Atmos — invokes a workflow via a customer-deployed reference runner;
terrantula import-atmosfor the on-ramp. - Atlantis — commits a PR your Atlantis instance picks up; typed trigger with run-output capture.
- OpenTofu — same shape as Terraform.
- Any HTTP endpoint — the native webhook trigger.
→ See the Triggers reference and the Examples gallery.
Get the on-ramp first
Import your existing state
terrantula import terraform (or terrantula import-atmos) reads your Terraform state and produces a fleet graph — no blueprint required. Visibility first; orchestration when you're ready.
Read-only graph dashboard
terrantula dashboard opens a graph view of the fleet derived from your state. It's a read-only projection — you never edit infrastructure in the UI; changes flow through Actions → PRs → your CI.
Drift awareness
Terrantula stamps imported entities with their source and observation time, so divergence between what your state says and what the graph holds is surfaced rather than silently lost.
→ Start with the Quick Start.
Run it your way
Self-hostable, end-to-end
The backend is Apache 2.0 and runs with zero SaaS dependencies — bring your own Postgres. The cattle wedge is fully functional self-hosted; nothing core is paywalled.
RBAC, multi-tenancy, and audit (hosted or self-hosted)
Organizations, projects, per-project API tokens, SSO/OIDC, role enforcement, immutable audit log, and soft-delete recovery are part of the unified backend. A hosted offering adds managed operations on top — it doesn't fork the API.
→ See Deploy on Kubernetes.