Learn
Reference
Examples
Learn
Reference
Examples

Catalog Schema Reference

Terrantula's catalog is declarative. You describe the model you want — the entity types you track, the cells you place tenants into, the relationships that order your fleet, the Actions that change infrastructure — as YAML, and apply it. apply reconciles that desired state against the graph the same way terraform apply reconciles HCL against real resources: created, updated, unchanged, deleted.

This is the lookup reference. One page per kind, each on the same template: synopsis → minimal example → fields table (grounded in @terrantula/types) → annotated example → caveats → related.

The kinds

There are seven catalog kinds, split into two phases by apply:

KindPhasePurpose
EntityTypeschemaThe kind of resource you track (TenantCluster, Tenant, Vpc). Declares states, properties, metrics.
CellschemaA placement-and-grouping unit over entities of one type (the cattle pen). Holds capacity constraints and a placement policy.
RelationshipTypeschemaThe kind of edge between two entity types (runs_on, depends_on).
ActionschemaA definition that mutates the graph and opens a pull request (or fires a TFC/Atmos/Atlantis run). Terrantula never runs terraform apply itself.
SecretschemaA named credential referenced by Actions and triggers. Encrypted at rest; the value is set out-of-band.
EntitydataA single tracked resource instance of an EntityType.
RelationshipdataA single edge instance of a RelationshipType between two entities.

The apply primitive is documented as its own page: it is the bulk-upsert that ingests every kind above, in dependency order.

YAML shape

Every kind accepts two equivalent shapes. The CLI and UI normalize both to the same flat form before validation:

Kubernetes-style envelope (what the canonical demos ship):

apiVersion: terrantula.io/v1
kind: EntityType
metadata:
  name: TenantCluster
spec:
  states: [provisioning, active, draining, decommissioned]
  initialState: provisioning

Flat shape (what the field tables on each page document, and what the API and SDK accept directly):

kind: EntityType
name: TenantCluster
states: [provisioning, active, draining, decommissioned]
initialState: provisioning

The envelope's metadata.name becomes the flat name; everything under spec is hoisted to the top level. The field tables on each kind's page describe the flat field names — in the envelope shape they live under spec (and name lives under metadata).

TIP

A single --file can hold many documents (----separated) of any kind. The CLI concatenates them into one apply request, so a whole blueprint applies atomically. See the canonical demosfor full blueprints.

Howapply ingests the catalog

terrantula apply --file blueprint.yaml

apply processes the catalog in two phases, auto-sorting within each by dependency order — so you never have to hand-order a blueprint:

  1. Schema phase — EntityType, Secret, Cell, RelationshipType, Action.
  2. Data phase — Entity, Relationship.

Schema-then-data ordering means a Cell referencing an EntityType, or an Entity of a freshly-declared type, resolves correctly inside one apply. Apply also supports dryRun (plan-only diff), force (allow breaking schema changes), and deletions. Full semantics are on the apply page.

Related

  • Catalog YAML Guide — the teaching tour of the YAML shape.
  • Core Concepts — entities, cells, relationships, Actions, the cascade.
  • Interpolation Reference — the {{ ... }} expression surface used in Action triggers and operations.
  • Examples — full blueprints for TFC, Atmos, Atlantis, and bare-TF + GitHub Actions.
  • API Reference — the project-scoped routes that back each kind.
ON THIS PAGE