#Action

An Action is the only way infrastructure changes in Terrantula. It pairs a graph operation (create/update/transition an entity or relationship) with an external trigger that does the real work — opening a pull request, firing a Terraform Cloud run, dispatching an Atmos workflow, or calling Atlantis.

Phase: schema. This is the largest kind — operations, triggers, recommendations, cascade rules, and per-env overrides are all defined here.

#Minimal example

kind: Action
name: SuspendTenant
associatedWith:
  entityType: Tenant
  scope: instance
operation:
  type: transition-entity
  onTrigger: suspending
  onSuccess: suspended
  onFailure: active
trigger:
  type: noop

#Fields

#AssociatedWith

#Condition

All conditions must pass for the Action to be offered on an entity (evaluated against the entity for instance-scoped actions).

#Recommendation

A cell-ranked placement suggestion. At trigger time Terrantula ranks the cell's members and proposes the best target; the selection is then available to the operation and trigger via {{ recommendations.<name>.* }}.

#Operations

operation is discriminated on type. Most carry onTrigger / onSuccess / onFailure states that drive the entity (or relationship) through its lifecycle as the ActionRun progresses.

#createRelationship

Inside a create-entity operation, optionally create a relationship from the just-created entity on success:

#Triggers

trigger is discriminated on type. Six types, covering the substrates Terrantula sits on top of — never replacing your runners.

#pull-request

#FileEntry

#FilePatch

Patch mode lets a cattle workflow extend a monolithic tfvars/yaml file without refactoring to one-file-per-tenant. Discriminated on type:

#postMergeDispatch

#terraform-cloud

Fires a run against a pre-existing workspace. Terrantula tracks the outcome; TFC runs the plan/apply.

#atlantis

Atlantis is always customer-hosted. Two modes:

#atmos-workflow

Invokes a named Atmos workflow on a customer-deployed reference runner. Terrantula never executes atmos directly.

#Cascade rules

cascadeRules (on create-entity and transition-entity operations) propagate changes along the graph when the parent entity enters a phase. Phases: on-trigger, on-success, on-failure. Two flavors, discriminated by which payload is present:

State-transition rule — move existing relationships into a new state:

createEntity rule — seed a sibling entity + a linking relationship:

#dependsOn

Sequences Apply Actions across the entity relationship graph — the high-level golden path. Both fields are literal name references (no interpolation), validated at apply.

Apply-time validation: DEPENDS_ON_RELATIONSHIP_NOT_FOUND, DEPENDS_ON_ACTION_NOT_FOUND, and DEPENDS_ON_CYCLE (the dependency graph, including edges from prior applies, must be acyclic).

#Per-env overrides

envOverrides is a map of env name → a partial of the base trigger (same type, validated at apply). At dispatch, override fields are shallow-merged over the base trigger. Use it to point dev/staging/prod at different repos, workspaces, or runner endpoints from one Action definition.

#Annotated example: create-entity + TFC

OnboardTenant from the SaaS-tenants demo — creates a Tenant, links it to the least-loaded cluster, and fires a TFC run:

apiVersion: terrantula.io/v1
kind: Action
metadata:
  name: OnboardTenant
spec:
  displayName: Onboard a new tenant
  associatedWith:
    entityType: Tenant
    scope: collection
  parameters:
    - { name: customer_id,       type: string, required: true }
    - { name: plan_tier,         type: string, enum: [basic, premium], required: true }
    - { name: region_preference, type: string, required: true }
  recommendations:
    - name: target-cluster
      title: Target cluster
      cell: prod-clusters
      sortBy: tenant-count
      order: asc
      required: true
  operation:
    type: create-entity
    entityType: Tenant
    onTrigger: provisioning
    onSuccess: active
    onFailure: failed
    properties:
      customer_id: "{{ parameters.customer_id }}"
      plan_tier: "{{ parameters.plan_tier }}"
    createRelationship:
      relationshipType: runs_on
      to: "{{ recommendations.target-cluster.id }}"
      onSuccess: active
      onFailure: removing
      properties:
        namespace: "tenant-{{ parameters.customer_id }}"
  trigger:
    type: terraform-cloud
    organization: my-org
    workspaceName: tenant-onboard
    apiToken: "{{ secrets.tfc-api-token }}"
    variables:
      customer_id: "{{ parameters.customer_id }}"
      region: "{{ recommendations.target-cluster.properties.region }}"
    autoApply: false
    waitForCompletion: true

#Annotated example: pull-request + dependsOn + postMergeDispatch

ApplyTenant from the multi-stack greenfield demo — opens a PR once all upstream applies have succeeded, then dispatches the apply workflow on merge:

kind: Action
name: ApplyTenant
associatedWith:
  entityType: Tenant
  scope: instance
dependsOn:
  - relationship: runs_in_aws_account
    appliedAction: ApplyAWSAccount
  - relationship: placed_on_cluster
    appliedAction: ApplyClusterBinding
operation:
  type: transition-entity
  onTrigger: applying
  onSuccess: active
  onFailure: failed
trigger:
  type: pull-request
  repo: "{{ project.iac_repo }}"
  auth:
    type: token
    token: "{{ secrets.github-token }}"
  title: "Apply Tenant {{ entity.name }}"
  head: "terrantula/apply-tenant-{{ entity.name }}"
  base: main
  files:
    - path: "infra/tenant/{{ entity.name }}/main.tf"
      content: |
        module "tenant" {
          source      = "../_modules/tenant"
          customer_id = "{{ entity.properties.customer_id }}"
        }
  webhookSecret: "{{ secrets.github-webhook-secret }}"
  postMergeDispatch:
    workflow: terrantula-entity-apply.yml
    eventType: terrantula-entity-apply
    payload:
      entity_id: "{{ entity.id }}"
      directory: "infra/tenant/{{ entity.name }}"

#Annotated example: transition-entity + cascade

DeprovisionTenant from the SaaS-tenants demo — transitions the tenant and cascades its runs_on edge to removing then removed:

kind: Action
name: DeprovisionTenant
associatedWith:
  entityType: Tenant
  scope: instance
conditions:
  - field: entity.state
    operator: eq
    value: active
operation:
  type: transition-entity
  onTrigger: deprovisioning
  onSuccess: decommissioned
  onFailure: active
  cascadeRules:
    - relationshipType: runs_on
      fromState: active
      toState: removing
      phase: on-trigger
      direction: from
    - relationshipType: runs_on
      fromState: removing
      toState: removed
      phase: on-success
      direction: from
trigger:
  type: terraform-cloud
  organization: my-org
  workspaceName: tenant-deprovision
  apiToken: "{{ secrets.tfc-api-token }}"
  variables:
    destroy_mode: "true"
  waitForCompletion: true

#Caveats

#Related

• EntityType — associatedWith.entityType, applier, mutatesProperty.
• Cell — recommendations[].cell ranks placement targets.
• RelationshipType — relationship operations and cascade rules.
• Secret — trigger auth.
• Interpolation Reference — the {{ parameters.* }}, {{ entity.* }}, {{ recommendations.* }}, {{ secrets.* }}, {{ run.* }} surface.
• Triggers, GitHub App, Actions & Webhooks · Actions & PR hygiene
• Wire an Action · Core Concepts