#Your First Fleet

You've learned the mindset, the vocabulary, and the YAML shapes, and you've applied your first cell. This section turns all of that into a complete, working fleet — built one primitive at a time, in the order you'd actually build it.

This is a guided, sequential tutorial. Do the steps in order; each one depends on the one before it, and each page ends pointing at the next. By the end you'll have imported your real Terraform state, modeled it as entity types and cells, connected it with a relationship, and wired an Action that opens a pull request to onboard a tenant — without ever asking Terrantula to run terraform apply.

#What you'll build

A small but complete tenant fleet, modeled on the canonical bare-tf-gh-actions-onefile-per-tenant demo:

• A TenantCluster entity type and a Tenant entity type — the two shapes in your fleet.
• A prod-clusters cell that groups your clusters and decides where the next tenant lands.
• A runs_on relationship type that connects tenants to clusters, with enforced cardinality and an explicit dependency order.
• An OnboardTenant Action whose trigger opens a GitHub pull request. Your CI applies the change on merge; Terrantula tracks the run and transitions the tenant when it lands.

When you're done, your dashboard shows a live graph of clusters, tenants, and the links between them — and you have a one-command way to grow the fleet that produces a reviewable PR every time.

#The step sequence

Follow these in order. Each builds on the last.

1. Import your TF state — bring your existing Terraform resources in as entities with terrantula import terraform. Start from reality, not a blank page.
2. Define entity types & cells — shape the imported resources into proper entity types and group your clusters into the prod-clusters cell.
3. Add relationships — connect tenants to clusters with the runs_on relationship type, and learn how dependsOn gives the cascade its ordering.
4. Wire an Action — declare OnboardTenant with a pull-request trigger. Terrantula opens the PR; your CI applies it.
5. Next Steps — where to go once your first fleet is live.

#Prerequisites

• The Terrantula CLI installed. See Install if you haven't yet. Everything below runs locally by default — no signup, no server, no Docker. The CLI writes to an embedded local database until you point it at a remote project.
• A Terraform .tfstate file for some real infrastructure — ideally a cluster or two you can model as the fleet's hosts. If you don't have one handy, the synthetic 50-resource fixture at examples/m1-timing/terraform.tfstate in the repository works for following along.
• You've read Learn Terrantula (or you're comfortable with entities, cells, relationships, and Actions). You don't need to have memorized the YAML — you'll copy real, runnable snippets as you go.

Ready? Start with the import — the cheapest, fastest way to get your real fleet on screen.

Next: Step 1 — Import your TF state →