RelationshipType

The kind of edge between two EntityTypes — runs_on, depends_on, placed_on_cluster. A RelationshipType declares the directed from/to types, the cardinality, the valid relationship states, and any per-edge properties. Every Relationship is an instance of one RelationshipType. Phase: schema.

Relationships are how Terrantula orders your fleet: they drive the cascade (state changes propagating along edges) and derived metrics (e.g. tenant-count = active runs_on edges into a cluster).

Minimal example

kind: RelationshipType
name: runs_on
from: Tenant
to: TenantCluster
states: [active]

Fields

Field	Type	Required	Description
`kind`	`"RelationshipType"`	yes	Discriminator. Always `RelationshipType`.
`name`	string	yes	Unique type name within the project. Referenced by Relationships, Action operations, and cascade rules.
`displayName`	string	no	Human label for the UI. Defaults to `name`.
`from`	string	yes	Name of the from-end EntityType. Must reference an existing EntityType.
`to`	string	yes	Name of the to-end EntityType. Must reference an existing EntityType.
`cardinality`	`"one-to-one" \| "one-to-many" \| "many-to-one" \| "many-to-many"`	no	Edge multiplicity. Default `many-to-many`.
`states`	string[]	yes	All valid states for an edge of this type.
`properties`	Property[]	no	Typed properties an edge carries. Default `[]`. Same shape as EntityType properties.
`constraints`	Constraint[]	no	Constraints enforced at create-relationship time. Default `[]`.

Constraint

A property-sum constraint caps the sum of a relationship property across all edges pointing at the same to-entity.

Field	Type	Required	Description
`type`	`"property-sum"`	yes	The only constraint type today.
`property`	string	yes	The relationship property to sum across all edges to the target entity.
`leq`	string	yes	Interpolation expression resolving to the ceiling value, e.g. `{{ to.metrics.available-cpu }}`.

Annotated example

The runs_on type from the SaaS-tenants demo. Many tenants per cluster, one cluster per tenant. The namespace property is the per-tenant Kubernetes namespace allocated by the Terraform run.

apiVersion: terrantula.io/v1
kind: RelationshipType
metadata:
  name: runs_on
spec:
  displayName: Runs On
  from: Tenant
  to: TenantCluster
  cardinality: many-to-one
  states: [assigning, active, migrating, removing]
  properties:
    - name: namespace
      type: string
      required: true
    - name: allocated_at
      type: string

Caveats

INFO

from and tomust reference existing EntityTypes. Declare them earlier in the same blueprint and the schema phase resolves the references in dependency order.

NOTE

The first state in states is the default state for a new Relationship when state is omitted. Order statesdeliberately.

WARNING

property-sum constraints are enforced at create-relationship time and are bypassed by migrate-relationship operations (see the Action migrate-relationshipoperation). This is intentional: a rebalancing move should not be blocked by the ceiling it is moving load away from.

EntityType — the from/to types and the property-sum ceiling source.
Relationship — an instance of a RelationshipType.
Action — relationship operations and cascade rules transition edges of a type.
Relationships · Core Concepts

ON THIS PAGE

#RelationshipType

#Minimal example

#Fields

#Constraint

#Annotated example

#Caveats