EntityType

The kind of resource Terrantula tracks — TenantCluster, Tenant, Vpc, EksCluster. An EntityType declares the valid lifecycle states, the typed properties an instance carries, and any derived metrics used for placement and capacity. Every Entity is an instance of one EntityType. Phase: schema.

Minimal example

kind: EntityType
name: Tenant
states: [pending, active, suspended]
initialState: pending

Fields

Field	Type	Required	Description
`kind`	`"EntityType"`	yes	Discriminator. Always `EntityType`.
`name`	string	yes	Unique type name within the project (e.g. `TenantCluster`). Referenced by Cells, RelationshipTypes, Actions, and Entities.
`displayName`	string	no	Human label for the UI. Defaults to `name`.
`states`	string[]	yes	All valid lifecycle states. `active` and `failed` are always implicitly available even if omitted.
`initialState`	string	yes	State assigned to a newly created Entity. Must be one of `states`.
`properties`	Property[]	no	Typed properties an instance carries. Default `[]`.
`metrics`	Metric[]	no	Named, sourced values (derived, pushed, or manual) used for capacity and placement. Default `[]`.
`constraints`	Constraint[]	no	Per-entity ceilings on a metric. Default `[]`.
`syncTracked`	boolean	no	Whether entities of this type carry a sync-freshness pill. Default `true`.
`syncFreshness`	SyncFreshness	no	Per-type override for the freshness pill thresholds.
`applier`	string	no	Name of an Action to auto-fire when an entity of this type is created. The Action must have `associatedWith.entityType` matching this type.

Property

A typed property definition (shared by EntityType, RelationshipType, and Action parameters).

Field	Type	Required	Description
`name`	string	yes	Property key.
`type`	`"string" \| "integer" \| "number" \| "boolean"`	yes	Value type.
`title`	string	no	Human label.
`description`	string	no	Help text.
`required`	boolean	no	Whether a value must be supplied. Default `false`.
`default`	string \| number \| boolean	no	Default value.
`enum`	string[]	no	Allowed values. Only valid when `type` is `string`.

Metric

A named value attached to entities of this type.

Field	Type	Required	Description
`name`	string	yes	Metric name (e.g. `tenant-count`).
`unit`	string	yes	Display unit — `integer`, `percentage`, `cores`, `GB`.
`source`	MetricSource	yes	How the value is computed.

MetricSource

Discriminated on type:

`type`	Extra fields	Behavior
`derived`	`derivedFrom: "relationship-count" \| "sum"`, optional `filter: { entityType?, relationshipType?, states? }`	Recomputed by Terrantula from matching relationships as they are created/deleted.
`push`	—	Set by an external pusher via the API.
`manual`	—	Set by hand.

Constraint

Field	Type	Required	Description
`metric`	string	yes	Name of a metric declared on this type.
`max`	number	yes	Per-entity ceiling for that metric.

SyncFreshness

Field	Type	Required	Description
`greenSeconds`	positive integer	no	Seconds after which an entity is no longer "fresh". UI default 300.
`yellowSeconds`	positive integer	no	Seconds after which an entity tips from "stale" to "very stale". UI default 3600.

Annotated example

The TenantCluster type from the SaaS-tenants demo. The tenant-count metric is derived — Terrantula recomputes it from the count of active runs_on relationships pointing at each cluster, so capacity decisions always reflect real allocation.

apiVersion: terrantula.io/v1
kind: EntityType
metadata:
  name: TenantCluster
spec:
  displayName: Tenant Cluster
  states: [provisioning, active, draining, decommissioned]
  initialState: provisioning
  properties:
    - name: region
      type: string
      required: true
    - name: tier
      type: string
      enum: [basic, premium]
      required: true
    - name: kubernetes_version
      type: string
      required: true
    - name: arn
      type: string
      description: AWS EKS cluster ARN
  metrics:
    - name: tenant-count
      unit: integer
      source:
        type: derived
        derivedFrom: relationship-count
        filter:
          relationshipType: runs_on
          states: [active]
  constraints:
    # Cap each cluster at 50 active tenants.
    - metric: tenant-count
      max: 50

The applier field wires an EntityType to an Apply Action — used in the multi-stack greenfield pattern where every entity owns its own Terraform stack:

kind: EntityType
name: AWSAccount
states: [pending, applying, active, deprovisioning, decommissioned, failed]
initialState: pending
applier: ApplyAWSAccount   # auto-fires when an AWSAccount entity is created
properties:
  - { name: customer_id, type: string, required: true }

Caveats

INFO

initialState must appear in states. active and failed are always available implicitly, so a type with states: [active] and initialState: activeis valid.

WARNING

Removing a state that entities are currently in, or removing a property that has existing values, is a breaking schema change. apply rejects it unless you pass force: true.

NOTE

A constraint is a per-entity ceiling. A fleet-wide ceiling lives on the Cell (constraints[].aggregate), not here.

NOTE

applier and the Action it names must agree: the Action's associatedWith.entityType must equal this type's name, validated at apply.

Cell — groups and places entities of one type.
RelationshipType — edges between two types.
Entity — an instance of an EntityType.
Action — applier and lifecycle Actions for a type.
Core Concepts · Catalog YAML Guide

ON THIS PAGE

#EntityType

#Minimal example

#Fields

#Property

#Metric

#MetricSource

#Constraint

#SyncFreshness

#Annotated example

#Caveats

#Related