#Learn Terrantula

Terrantula is the fleet layer for Terraform. When you run the same Terraform a hundred times — per-customer stacks, per-region cells, per-PR ephemeral environments — the individual resources stop mattering and the population becomes the problem. Terrantula sits on top of whatever runs your Terraform today (Terraform Cloud, Atmos, Atlantis, or plain GitHub Actions with state in S3) and adds typed entities with lifecycle, cell placement with capacity limits, relationships with cardinality, and Actions that change your IaC by opening pull requests.

Terraform names your pets. Terrantula herds your cattle.

This section is a deliberate staircase: concepts before commands, then a guided build, then hands-on tutorials. But you don't have to start at step one — the persona router below lets you jump in at the problem you actually have.

#The four foundational ideas

Everything in the Learn staircase rests on four ideas. You'll meet them in depth in Core Concepts; here they are in one breath:

• Entities and cells. An entity is one head of cattle — a tenant, an environment, an account — typed by an entity type. A cell is where entities are placed (a region, a cluster, a shard), with capacity limits enforced by Terrantula.
• Relationships and the cascade. Entities relate to each other (dependsOn, placedIn) with enforced cardinality. Those relationships define the order in which work cascades across the fleet — upstream entities settle before their dependents proceed.
• Actions open pull requests. An Action is a fleet operation (onboard a tenant, deprovision one). Terrantula never runs terraform apply. Actions open PRs against your IaC repo; your existing CI applies on merge.
• The graph is a read-only projection. The view Terrantula renders is derived from your Terraform-described state. It never writes your infrastructure — all changes flow through Actions and PRs.

These hold across every substrate and every persona. Terrantula is Apache 2.0 and self-hostable end-to-end — the whole cattle wedge runs with zero SaaS dependencies.

#Find your starting point

Where are you with your Terraform fleet? Pick the card that sounds like your week.

#Get going

When you're ready to do it rather than read about it:

• Quick Start → — the first five minutes. terrantula import terraform your existing state, then terrantula dashboard for a working graph view. No signup, no server, no Docker. (Start here.)
• The Cattle Mindset — the pets-vs-cattle essay. Why the population matters more than the resource, and what that changes about how you operate.
• Core Concepts — the full vocabulary: entities, entity types, cells, relationships, relationship types, Actions, secrets, and the cascade.

#The full staircase

The sidebar lays out the complete zero-to-competent path. In order:

1. Get Started — install the CLI, learn what Terrantula is, and find the on-ramp that matches your runner (bare Terraform + GitHub Actions, Terraform Cloud, or Atmos).
2. Learn Terrantula — the cattle mindset, core concepts, the catalog YAML guide, and defining your first cell. Model before commands.
3. Your First Fleet — a guided build of the primitives in order: import your state, define entity types and cells, add relationships, wire an Action.
4. Quick Start — end-to-end and hands-on, at two depths: the five-minute Simple path and an Advanced multi-stack cascade.
5. Best Practices — now do it well: modeling, cascade design, Action and PR hygiene, multi-tenancy, and self-hosting.
6. Troubleshoot — reactive recovery: common errors, import issues, Action/PR debugging, and drift.