Skip to content

glitchtip-operator

A Kubernetes operator (Rust, kube-rs) that deploys GlitchTip instances and manages organizations, teams and projects declaratively — delivering each project's DSN as a Secret in the consuming application's namespace.

What it manages

CRD Short name Purpose
GlitchTip gt Full instance: web + worker Deployments, migration & bootstrap Jobs, PostgreSQL via pgop, optional Valkey, Service, optional Gateway API HTTPRoute
GlitchTipOrganization gtorg Organization inside an instance (via the GlitchTip REST API)
GlitchTipTeam gtteam Team inside an organization
GlitchTipProject gtproj Project + client key; writes the DSN Secret next to the CR

The chain is: GlitchTipProject → GlitchTipOrganization → GlitchTip, with teams referenced by teamRef or a raw teamSlug.

graph LR
  GT[GlitchTip] --> GTORG[GlitchTipOrganization]
  GTORG --> GTTEAM[GlitchTipTeam]
  GTORG --> GTPROJ[GlitchTipProject]
  GTTEAM -. teamRef/teamSlug .-> GTPROJ
  GTPROJ --> DSN[(DSN Secret)]

Start with Installation, then the Quick Start to stand up a full instance and DSN in a few kubectl applys.

How it works

  • PostgreSQL is provisioned by creating pgop Cluster/Role/Database CRs in the instance's namespace (or an existing pgop Cluster via spec.database.clusterRef). The operator composes DATABASE_URL from pgop's <database>-<owner>-credentials Secret. spec.database.deletionPolicy defaults to Retain, so deleting a GlitchTip CR keeps your data.
  • Migrations run as a per-revision Job (./bin/run-migrate.sh) and gate web/worker rollout.
  • API token bootstrap: the operator pre-generates a token into <name>-api-token, then a one-shot Job creates a superuser service account and inserts the token via manage.py shell. Pre-existing instances can supply spec.apiTokenSecretRef instead.
  • Valkey is optional (spec.valkey.enabled) — GlitchTip v5.2+ can use PostgreSQL as its cache/celery/session backend instead. When disabled, the operator sets VALKEY_URL="" (explicitly empty, not merely unset) to activate it; versions before v5.2 have no such fallback and require Valkey.
  • HTTPRoute (spec.route) attaches the web Service to your Gateway; if the Gateway API CRDs are absent the instance reports Ready=False/GatewayAPIUnavailable instead of crashing.
  • Drift healing: every CR re-reconciles on a 5-minute cadence; orgs, teams, projects, keys and Secrets deleted or mutated out-of-band are recreated/rewritten (Secrets via server-side apply ownership).
  • Deletion: deletionPolicy: Delete (default for org/team/project) removes the object via the GlitchTip API through a finalizer; Retain releases the CR without touching GlitchTip. Finalizers never wedge when the parent instance is already gone.

Organization/team/project slugs

GlitchTip's API always derives an organization's slug from its display name on creation and ignores any client-requested slug — see Organizations for how the operator handles this.