Entity

A single tracked resource instance — one tenant, one cluster, one VPC. An Entity is an instance of an EntityType and is identified by its name. Phase: data (applied after the schema phase).

INFO

You usually do not apply entities directly. The graph is a read-only projection of TF-derived state: entities arrive via import-terraform or are created by Actions (which open pull requests). Applying an Entity by hand is for importingexisting resources (e.g. migrating from a homegrown allocation system) or seeding a demo.

Minimal example

kind: Entity
entityType: Tenant
name: acme

Fields

Field	Type	Required	Description
`kind`	`"Entity"`	yes	Discriminator. Always `Entity`.
`entityType`	string	yes	Name of the EntityType this is an instance of. Must reference an existing EntityType.
`name`	string	yes	Unique entity name within its type. Used to resolve relationships and as the upsert key.
`state`	string	no	Lifecycle state. Omit to use the EntityType's `initialState`. When set, must be a valid state declared on the EntityType.
`properties`	object	no	Property values keyed by property name. Default `{}`.
`labels`	object (string→string)	no	Free-form string labels for filtering and grouping. Default `{}`.

Annotated example

The acme tenant from the SaaS-tenants demo — what the entity looks like in the graph after OnboardTenant succeeds, or how you would declaratively import an existing tenant:

apiVersion: terrantula.io/v1
kind: Entity
metadata:
  name: acme
spec:
  entityType: Tenant
  state: active
  properties:
    customer_id: acme
    plan_tier: premium
    region_preference: us-east-1
    contact_email: ops@acme.example

Caveats

INFO

properties are validated against the EntityType's declared properties. A required property with no value, or a value violating a property enum, fails at apply.

NOTE

state, when supplied, must be one of the EntityType's states (or the implicit active/failed). Omit it to take the type's initialState.

WARNING

Direct entity writes do not run the EntityType's applier Action or any lifecycle cascade — they set state as-declared. Lifecycle changes that should flow through infrastructure belong in an Action, which opens a pull request; Terrantula never runs terraform applyitself.

EntityType — the type whose properties and states this instance must satisfy.
Relationship — edges between entities.
Action — the lifecycle path that creates and mutates entities via PRs.
Import your TF state · Core Concepts

ON THIS PAGE

#Entity

#Minimal example

#Fields

#Annotated example

#Caveats

#Related

Entity

Minimal example

Fields

Annotated example

Caveats

Related