#Glossary

The cattle-wedge vocabulary, one term per row. Each definition is one or two sentences; follow the link for the full treatment.

#A

Action — A declarative workflow you fire against entities. It validates parameters, evaluates conditions, runs placement, mutates the graph, and opens a pull request (or fires a TFC / Atmos / Atlantis run) to reach your infrastructure. Terrantula never runs terraform apply itself. See Action.

ActionRun — The record of one firing of an Action: who fired what, with which parameters, and how it ended (succeeded / failed). Your audit trail and the unit a merge webhook completes. See Core Concepts → Actions.

apply — The bulk-upsert primitive. Reconciles a list of catalog kinds against the project graph in one request — created, updated, unchanged, deleted — the way terraform apply reconciles HCL against real resources. Supports dryRun, force, and deletions. See apply.

Aggregate constraint — A limit applied across a whole cell, such as "≤ 500 tenants summed across every cluster." Distinct from a per-entity constraint. See Cell.

#C

Cardinality — The enforced shape of a relationship type: one-to-one, one-to-many, many-to-one, or many-to-many. Terrantula rejects links that break it. See RelationshipType.

Cascade — The mechanism that propagates a state change across relationships in dependency order — e.g. a tenant entering deprovisioning transitions its runs_on relationships to removing so nothing is torn down before its dependents. Declared as cascadeRules on an Action and fired at the on-trigger / on-success / on-failure phases. See Action → Cascade rules.

Catalog — The whole declarative model of your fleet: the set of YAML documents (entity types, cells, relationship types, Actions, secrets, plus entity/relationship data) that you apply. See Catalog Schema Reference.

Cell — A named group of entities of one type with a placement policy and aggregate constraints — the cattle pen. Answers "where should the next thing go, and what limits apply across the group." See Cell.

Constraint — A hard limit expressed against a metric. On an entity type it caps the individual ("≤ 50 tenants per cluster"); on a cell it caps the fleet. See EntityType → Constraint.

#D

dependsOn — A field on an Action that sequences Actions across the relationship graph: "before this Action runs, the upstream entity's apply must have succeeded." How a multi-stack onboard orders itself (cluster before tenant) without hand-sequencing runs. Must be acyclic, or apply rejects it with DEPENDS_ON_CYCLE. See Action → dependsOn.

Drift — The gap between what Terrantula last ingested and what your state backend now says. Sync drift is a per-entity status (current / stale / missing) against the external source; drift events are an intra-Terrantula reconciler's records. Close drift by re-ingesting — never by editing the graph. See Drift & state issues.

Dry run — A plan-only apply (dryRun: true, CLI --dry-run): no writes, returns a diff of what would be created / updated / unchanged / deleted. See apply → Dry-run diff.

#E

Entity — A single instance of an entity type: one actual tenant, one actual cluster. A typed, stateful record that is a projection of your Terraform, not the source of truth. See Entity.

Entity Type — The shape of a thing in your fleet — its states, properties, metrics, and constraints. A definition, not a thing (like a class versus an object). See EntityType.

#M

Metric — A measured value attached to entities, often derived automatically (e.g. a cluster's tenant-count is computed from its active runs_on relationships). The thing constraints and placement sort on. See EntityType → Metric.

#P

Placement policy — How a cell ranks its members when something needs a home: least-loaded (default), round-robin, or random. The fleet decision Terraform was never going to make for you. See Cell.

Property — A typed field declared on an entity type or relationship type (region, plan_tier); may be required or carry an enum. See EntityType → Property.

Pull request — How an Action's default trigger reaches your infrastructure: it commits files to a branch and opens a PR. Your CI runs terraform apply on merge. See Action → pull-request.

#R

RBAC — Role-based access control: every project-scoped route requires a permission string (catalog:read, data:write, apply:write, …). See RBAC & Drift.

Relationship — A single instance of a relationship type: one actual, directional, stateful link between two specific entities ("tenant acme runs on cluster eks-us-east-1"). See Relationship.

Relationship Type — The shape of a connection between two entity types: directional, typed, with a cardinality and its own states and properties (runs_on, depends_on). See RelationshipType.

#S

Secret — A named, encrypted credential referenced by Actions and triggers ({{ secrets.tfc-api-token }}). Declared by name in the catalog; the value is set out-of-band and never lands in YAML, version control, or logs. See Secret.

State — A lifecycle position an entity or relationship can occupy (e.g. pending → provisioning → active → suspended), declared on its type with an initialState. What lets Terrantula answer "how many tenants are active now?" See EntityType.

Substrate — The IaC tooling Terrantula sits on top of: Terraform first, Atmos as a peer, OpenTofu second — plus the runner that applies it (bare TF + GitHub Actions, Terraform Cloud, Atlantis). Terrantula never replaces the substrate or hosts its runner. See Triggers Reference.

#T

Trigger — The block on an Action that knows how the change reaches your runner. Pluggable: pull-request (default), terraform-cloud, atlantis, atmos-workflow, webhook. Swapping the trigger leaves the operation and placement logic unchanged. See Action → Triggers.