#Step 1 — Import your TF state

Every fleet starts from infrastructure that already exists. Before you write a single entity type by hand, you bring your real Terraform state in as entities — so you're modeling reality, not a blank page. This is the cattle on-ramp: a graph view of what you actually run, in one command.

By the end of this step you'll have your existing clusters (and whatever else is in your state) showing up as entities in Terrantula's local database, ready to shape in Step 2.

#What import does

terrantula import terraform reads a Terraform state file, maps each resource to a Terrantula entity using a small mapping config you provide, and applies the result. It's the same apply pipeline you'd use for hand-written catalog YAML — import just generates the entity documents for you from your state.

Two things make it safe to run against real infrastructure:

• It never touches Terraform. Import reads a state file (or pulls one from S3 / Terraform Cloud). It does not plan, apply, or modify anything. The entities it creates are a read-only projection of your infrastructure.
• It's idempotent. Run it again after your state changes and existing entities are updated in place; new resources are added. Nothing is destroyed unless you explicitly pass --replace.

#The mapping config

Import needs to know which Terraform resource types become which entity types, and how to fill in their properties. You give it that in a YAML mapping config. Here's a minimal one — save it as tf-mapping.yaml:

sources:
  - path: terraform.tfstate
    labels:
      env: prod

mappings:
  aws_eks_cluster:
    entity_type: TenantCluster
    name: '{{ .name }}'
    properties:
      region: '{{ .arn | split ":" | index 3 }}'
      arn: '{{ .arn }}'
    labels:
      cell: '{{ .tags.cell | default "unassigned" }}'

Read it top to bottom:

• sources — the state file(s) to read. labels here tag every entity from this source (handy for filtering later).
• mappings — one entry per Terraform resource type. The key (aws_eks_cluster) is the TF type; entity_type is the Terrantula entity type each matching resource becomes.
• name and properties use Go-template interpolation against each resource's attributes. {{ .name }} is the resource's name; {{ .arn | split ":" | index 3 }} pulls the region out of an EKS ARN; | default "..." supplies a fallback when an attribute is absent.

You don't have to write this from scratch. Terrantula ships starter configs you can compose with extends: — aws-multi-account, kubernetes-inventory, and multi-tenant-cells cover the common shapes. To build on one, reference it and override just what you need:

extends:
  - terrantula/starters/aws-multi-account

sources:
  - path: terraform.tfstate

#Run the import

Point the command at your state file and your mapping config:

terrantula import terraform \
  --state ./terraform.tfstate \
  --config ./tf-mapping.yaml

--state is a URI: a local path, s3://bucket/key, or tfc://org/workspace. Repeat the flag to merge several state files into one fleet. --config is the path to the mapping config above.

You'll see a summary like:

Notice import auto-creates a stub TenantCluster entity type if one doesn't exist yet — enough for the entities to land. In Step 2 you'll replace that stub with a proper, fully-typed definition.

#See it in the dashboard

Open the local fleet view:

terrantula dashboard

Your browser opens to the entity browser. You'll see your clusters as TenantCluster entities — your real infrastructure, on one screen, derived straight from state. There are no tenants and no relationships yet; that's exactly what the next steps add.

#Derived-relationship suggestions

After applying entities, the importer scans for property values that match another entity's name across types. When it finds a match — say, a tenant whose cluster property equals the name of a Cluster entity — it suggests a derivedFrom relationship type as commented YAML:

The importer never auto-creates domain relationships. It suggests structural facts — cardinality, the join property — and leaves naming and containment to you. Promote the suggestion by adding a suggest_relationships.overrides entry to your mapping config. For example, to rename tenant_cluster to runs_on with explicit containment:

suggest_relationships:
  overrides:
    - from: Tenant
      to: Cluster
      property: cluster
      name: runs_on
      cardinality: many-to-one
      containment: true

The next run emits name: runs_on and containment: true (committed, not hinted). When you're satisfied, paste the uncommented block into your blueprint and apply it.

#Cross-stack joins

The suggestion engine works across statefiles. If your tenant stack references your cluster stack via terraform_remote_state, the importer detects that the tenant's cluster property value came from a remote-state output and annotates the suggestion:

The (cross-stack via clusters) note names the terraform_remote_state data source that exposed the value. The entity also gains a tf_source_stack: clusters label for filtering and provenance tracking.

At query time the derived edge resolves by joining Tenant.cluster == Cluster.name across all entities in the environment — regardless of which statefile each entity came from. There is no Terraform reference required at resolve time; the join is on entity properties.

A complete worked example — two statefiles, a mapping config with overrides, and the full importer output — lives in examples/cattle-multi-stack-greenfield/import-fixtures/.

#What you just did

• Wrote a mapping config that turns Terraform resource types into Terrantula entity types.
• Imported real state as entities — read-only, idempotent, no terraform apply in sight.
• Reviewed the importer's derived-relationship suggestions and learned how to promote them.
• Confirmed the fleet on screen with terrantula dashboard.

You now have entities, but they're shaped by a thin auto-generated stub. Next you'll give them a proper definition — lifecycle states, typed properties, derived metrics — and group your clusters into a cell that can place tenants.

Prev: ← Your First Fleet (overview) · Next: Step 2 — Define entity types & cells →