#On-ramp: From Terraform Cloud

This is the on-ramp for teams running Terraform Cloud (HCP Terraform). Your workspaces, your runs, your state, your VCS connections — all of it stays in TFC. Terrantula sits on top of it and complements it: it adds the fleet layer above your workspaces and triggers TFC runs natively when an Action fires.

Terrantula does not replace your runner. TFC keeps executing your Terraform.

#Where you are now

You manage Terraform through TFC workspaces. State and runs are hosted by TFC. You push to VCS or trigger runs through the TFC API, and TFC plans and applies. What you don't have is a fleet-wide view across workspaces — placement, capacity ceilings, and the relationships between the things your workspaces produce live in spreadsheets and tribal knowledge.

#What Terrantula adds

Terrantula is the fleet layer above TFC:

• Visibility across workspaces. A graph of every entity in the fleet — derived from your TFC-hosted state — with the cells they're placed in and how they connect.
• Placement and constraints. Typed entities with capacity ceilings and cardinality checks, so "we cap at 50 tenants per cluster" is enforced rather than remembered.
• Native TFC triggering. When an Action fires, Terrantula uses the terraform-cloud trigger to start a run in your TFC workspace, then polls until the run reaches a terminal state and advances the entity's lifecycle accordingly.

#Step 1 — Get a view, reading directly from TFC

Start with pure visibility. The CLI can read state directly from a TFC workspace — pass a tfc://org/workspace URI to --state:

terrantula import terraform --state tfc://my-org/prod-us-east-1 --config terrantula.yaml

Authenticate to TFC with a bearer token. Pass it with --tfc-token, or set the standard Terraform env var TF_TOKEN_app_terraform_io (or TFC_TOKEN):

export TF_TOKEN_app_terraform_io=<your-tfc-team-or-user-token>
terrantula import terraform --state tfc://my-org/prod-us-east-1 --config terrantula.yaml

Repeat --state to fold several workspaces into one fleet graph:

terrantula import terraform \
  --state tfc://my-org/prod-us-east-1 \
  --state tfc://my-org/prod-us-west-2 \
  --config terrantula.yaml

Preview first with --plan (an alias for --dry-run), then open the dashboard:

terrantula import terraform --state tfc://my-org/prod-us-east-1 --config terrantula.yaml --plan
terrantula dashboard

The --config file maps TFC-managed resources to Terrantula entity types and relationships. For the step-by-step walkthrough — including the starter configs that map common resources — follow the Quick Start.

#Step 2 — Add orchestration with the TFC trigger (optional)

When you grow into a cattle problem — placement, capacity, templated onboarding — turn on Actions backed by the terraform-cloud trigger:

1. You fire an Action (e.g. OnboardTenant). Terrantula validates parameters, enforces constraints, and picks the right cell.
2. Terrantula opens a PR against your repo with the new per-tenant IaC, and/or fires a run in the chosen TFC workspace.
3. TFC plans and applies on its own runners — your existing TFC policy checks, approvals, and Sentinel/OPA gates all still apply.
4. Terrantula polls the TFC run until it reaches a terminal state and advances the entity's lifecycle (e.g. to active) on completion.

The Terrantula catalog is identical to the bare-TF and Atmos variants; only the trigger configuration changes. See the cattle-saas-tenants demo, which is the TFC variant.

#What stays the same

• Your runner. TFC keeps planning and applying on its own runners. Terrantula never runs Terraform.
• Your state. It stays in TFC. Terrantula reads state via the TFC API; it never hosts it.
• Your TFC governance. Workspace settings, run triggers, policy checks, approvals, VCS connections — untouched.
• Your credentials. Provider credentials stay in TFC. Terrantula only needs a read/run-trigger TFC token.

Terrantula adds the fleet view, placement, constraint enforcement, and lifecycle — it points at TFC rather than around it.

#Next

• Quick Start — import your state and open the dashboard end-to-end.
• FAQ — how Terrantula differs from TFC and Spacelift.
• Triggers reference — the terraform-cloud trigger, in detail.
• Examples — the cattle-saas-tenants TFC canonical demo.