#Drift events

A drift event records that one field of an entity's stored properties diverges from what a configured reconciler observed in an external source. The reconciler runs periodically, writes one event per drifted (entity, field), and surfaces them for an operator to accept, reapply, or snooze.

This is the lookup reference for the drift_events record, the event lifecycle, the reconciler's behavior, and the API/SDK surface.

#Event fields

Each drift event the API returns has these fields. The list/get response joins in the entity's name and entityTypeName for convenience; the rest map directly to the drift_events row.

There is at most one open event per (entity, fieldPath) — a partial unique index enforces it, so a re-detection of the same drift updates the existing open row rather than piling up duplicates.

#Statuses

#Reconciliation policies — accept vs. reapply

When an operator resolves an open event they choose a direction:

#The reconciler

A background worker sweeps configured sources on a fixed cadence (default 15 minutes; overridable per project via projects.metadata.driftIntervalSeconds). For each source it:

1. Observes the source's view of every entity it covers.
2. Diffs each observation against the matching catalog entity's properties, comparing top-level keys (deep-equal by value).
3. Upserts one open event per drifted field. Re-detecting the same drift refreshes actualValue and detectedAt on the existing open row.
4. Auto-closes open events for that entity whose field no longer drifts — they move to accepted (catalog and actual agreed at observe time, so no operator action is needed).

The reconciler is advisory-locked so it never overlaps across server pods.

#Sources

The shipped source kind is bare-tf: it reads a Terraform state file from a sandboxed, project-scoped path and maps resources to entities via a type map. Configured under a project's metadata.drift.sources. An OSS / single-tenant deployment can point the reconciler at one state file with the TERRANTULA_OSS_TFSTATE_PATH environment variable, with no projects table involved.

#API surface

Drift events are environment-scoped, under /:org/:project/envs/:envName/drift-events. Reads require data:read (every role); the resolution POSTs require data:write (member and above) — see RBAC roles & permissions.

The resolution endpoints act only on open events — accepting, reapplying, or snoozing an already-resolved event returns 404.

Full request/response schemas are in the generated Drift Events API reference.

#SDK

The TypeScript SDK exposes the same surface through driftEvents:

import { createClient } from '@terrantula/sdk'

const client = createClient('https://your-terrantula-host', 'your-api-token')

// List open drift events for an env
const open = await client.driftEvents.list({
  orgId: 'acme',
  projectId: 'fleet',
  envName: 'prod',
  status: 'open',
})

// Resolve one by accepting the observed value into the catalog
await client.driftEvents.accept({
  orgId: 'acme',
  projectId: 'fleet',
  envName: 'prod',
  id: open[0].id,
})

// Or snooze it for 6 hours
await client.driftEvents.snooze({
  orgId: 'acme',
  projectId: 'fleet',
  envName: 'prod',
  id: open[0].id,
  untilSeconds: 6 * 60 * 60,
})

The client mirrors the API: list, count, get, accept, reapply, and snooze.

#Caveats

#Related

• RBAC roles & permissions — the data:read / data:write gates on this surface.
• Cross-source drift how-to — the external-source reconciliation flow (a separate system).
• Drift Events API — generated request/response schemas.
• Entity — the properties that drift is detected against.
• Terrantula Actions (GitHub Actions) — how a reapply reaches infrastructure (via a PR).
• Configuration Reference — drift reconciler config keys and environment variables.