#Cattle: per-tenant SaaS (Terraform Cloud)

Tags: Quickstart · Substrate · Modeling · Automation Substrate: Terraform Cloud

The canonical demo for the cattle wedge. You run a vertical SaaS with isolated per-customer infrastructure, a fleet of clusters with capacity ceilings, and tenants placed onto the least-loaded matching cluster. One command onboards a tenant.

#What you'll see

A single OnboardTenant action that:

• Validates parameters against the action schema.
• Queries the prod-clusters cell for a recommendation, sorted by tenant-count ascending (least-loaded first) and filtered by region and tier.
• Creates a Tenant entity in provisioning state.
• Fires a Terraform Cloud run via the typed terraform-cloud trigger — Terrantula resolves the workspace by name, queues a run, and polls until the run reaches a terminal state.
• On success, creates a runs_on relationship between the tenant and the chosen cluster and transitions the tenant to active; on failure, transitions to failed and records the cause.

Terrantula enforces the per-cluster cap (50 tenants), the fleet-wide cap (500 tenants across prod-clusters), region/tier matching, and the tenant lifecycle. Terrantula queues the TFC run; TFC applies it — Terrantula never runs terraform apply itself.

#Try it

Bring your own Terraform Cloud organization and a workspace (named tenant-onboard, or override via workspaceName / workspaceId in blueprint.yaml). The workspace must already exist — Terrantula does not create workspaces.

# 1. Apply the blueprint (entity types, the prod-clusters cell, the runs_on
#    relationship type, and the OnboardTenant action).
terrantula apply --file blueprint.yaml

# 2. Set the TFC API token as a secret.
terrantula secrets set-value tfc-api-token --value "$TFC_API_TOKEN"

# 3. Register at least one TenantCluster entity matching a real cluster.
terrantula entities create TenantCluster \
  --property region=us-east-1 \
  --property tier=premium \
  --property kubernetes_version=1.30 \
  --property arn=arn:aws:eks:us-east-1:123456789012:cluster/prod

# 4. Fire an onboard.
terrantula actions trigger OnboardTenant \
  --param customer_id=acme \
  --param plan_tier=premium \
  --param region_preference=us-east-1 \
  --param contact_email=ops@acme.example

Terrantula creates the run in TFC, polls until terminal state, and transitions the tenant to active (or failed). The TFC run URL is captured on the ActionRun's metadata field; the dashboard surfaces a click-through.

#Key files

#Related docs

• Quick Start (5 minutes) — import-terraform then dashboard.
• Core Concepts — entities, cells, relationships, the cascade.
• Triggers Reference — the typed terraform-cloud trigger.
• Action schema reference — the Action kind.
• On-ramp: from Terraform Cloud.

#View on GitHub

examples/cattle-saas-tenants