Relationship

A single directed edge between two Entities — "tenant acme runs_on cluster prod-cluster-use1-a". A Relationship is an instance of a RelationshipType, identified by its type plus its from/to endpoints. Phase: data (applied after the schema phase).

INFO

Like entities, relationships are usually created by Actions (which open pull requests) or by import — the graph is a read-only projection of TF-derived state. Applying a Relationship directly is for importingexisting edges or seeding a demo.

Minimal example

kind: Relationship
relationshipType: runs_on
from: acme
to: prod-cluster-use1-a

Fields

Field	Type	Required	Description
`kind`	`"Relationship"`	yes	Discriminator. Always `Relationship`.
`relationshipType`	string	yes	Name of the RelationshipType this is an instance of. Must reference an existing RelationshipType.
`from`	string	yes	The from-entity, by name or ID. Resolved against existing entities at apply.
`to`	string	yes	The to-entity, by name or ID. Resolved against existing entities at apply.
`state`	string	no	Edge state. Omit to use the first state declared on the RelationshipType. When set, must be a valid state on the type.
`properties`	object	no	Property values keyed by property name. Default `{}`.
`labels`	object (string→string)	no	Free-form string labels. Default `{}`.

Annotated example

The acme → prod-cluster-use1-a edge from the SaaS-tenants demo. from and to reference entities by name; namespace is the per-tenant Kubernetes namespace:

apiVersion: terrantula.io/v1
kind: Relationship
metadata:
  name: acme-runs_on-prod-cluster-use1-a
spec:
  relationshipType: runs_on
  from: acme
  to: prod-cluster-use1-a
  state: active
  properties:
    namespace: tenant-acme
    allocated_at: "2026-05-08T14:22:00Z"

NOTE

In the envelope shape, metadata.name is a human label for the document only. A relationship is identified by relationshipType + from + to, not by a name — the nameis not a relationship field and is dropped on normalization.

Caveats

INFO

from and to must resolve to existing entities at apply time. Because relationships are in the dataphase (after entities), you can declare both entities and the edge in the same blueprint.

WARNING

from/to entity types must match the RelationshipType's from/to types, and any property-sum constraint on the type is enforced at create time. A move that would exceed a ceiling is rejected unless performed via a migrate-relationship Actionoperation, which bypasses the constraint.

RelationshipType — the type, its endpoints, states, and constraints.
Entity — the endpoints a relationship connects.
Action — relationship operations and cascade rules.
Relationships · Core Concepts

ON THIS PAGE

#Relationship

#Minimal example

#Fields

#Annotated example

#Caveats

#Related

Relationship

Minimal example

Fields

Annotated example

Caveats

Related