Zum Inhalt

Terraform

Diese Seite erklärt, wofür wir Terraform einsetzen, nämlich nur für Authentik, und so viel von Terraform, wie man dafür braucht. Sie begründet auch, warum der State unverschlüsselt im Repo liegt. Warum wir Authentik überhaupt per Code verwalten, steht in Authentik.

Wo Terraform liegt

Terraform verwaltet bei uns nur Authentik, in zwei Ordnern:

Ordner Inhalt
apps/authentik/tf-core/ Grundeinstellungen und Branding, je App eine Datei application_<app>.tf mit allem, was zur Anbindung gehört, die Access-Gruppen und die Property Mappings
apps/authentik/tf-groups/ die Gruppen innerhalb der Apps (Rollen) und die Rolle für die Gruppenverwaltung

Jeder Ordner wird für sich ausgerollt und hat seinen eigenen State. Was die Einträge in Authentik bedeuten, erklären Authentik und Gruppenmodell in Authentik.

Authentik verwalten wir mit Terraform, obwohl es kompliziert ist. Terraform ist recht kompliziert, wenn man es nicht täglich benutzt; wer nur ab und zu eine App in Authentik anbindet, muss sich jedes Mal wieder hineindenken. Für Authentik gibt es aber nichts Besseres: Der Hersteller bietet einen offiziellen Terraform-Provider an, und alles Selbstgebaute, das die API von Authentik ansteuert, wäre am Ende ähnlich kompliziert und müsste zusätzlich von uns gepflegt werden.

Was man von Terraform wissen muss

Provider
Die Erweiterung, über die Terraform mit einem Dienst spricht. Wir nutzen nur den Authentik-Provider goauthentik/authentik, den der Hersteller von Authentik selbst anbietet (siehe Grundsätze). Welche Version, steht in main.tf jedes Ordners; die genaue Version mit Prüfsumme hält Terraform in .terraform.lock.hcl fest.
Resource
Ein Objekt, das Terraform anlegt und verwaltet, zum Beispiel eine Application oder eine Gruppe in Authentik. In den .tf-Dateien beginnt jede mit resource "<typ>" "<name>", etwa resource "authentik_group" …. Mit data beginnen Einträge, die Terraform nur liest, aber nicht verwaltet, etwa die mitgelieferten Flows in tf-core/dependencies.tf.
plan und apply
Wie bei syslet: terraform plan zeigt, was sich in Authentik ändern würde, terraform apply zeigt es noch einmal, fragt nach und führt es aus. Terraform läuft auf deinem Rechner und spricht direkt mit der API von Authentik; CUE ist nicht beteiligt. Bei Authentik meldet es sich mit einem API-Token an, das man beim Aufruf als Variable authentik_token mitgibt.
State
Die Datei terraform.tfstate, in der Terraform festhält, welche Objekte es in Authentik angelegt hat und wie sie eingerichtet sind. Nur was im State steht, verwaltet Terraform; Objekte, die jemand in der Web-Oberfläche anlegt, kennt es nicht. Ändert jemand dagegen ein verwaltetes Objekt in der Web-Oberfläche, zeigt das nächste plan die Abweichung. Nach jedem apply ändert sich der State und wird mit committet. Von Hand zusammenführen lässt er sich nicht; deshalb führt immer nur eine Person Terraform aus, nach Absprache in Signal (siehe Terraform für Authentik ausführen). Ein Git-Konflikt im State heißt, dass dabei etwas schiefgelaufen ist.

Welche Terraform-Version wir nutzen, steht je Ordner in .tool-versions, zum Beispiel apps/authentik/tf-core/.tool-versions. Versionsmanager wie asdf oder mise lesen die Datei und nehmen die passende Version von selbst.

Wie man Terraform ausführt, steht in Terraform für Authentik ausführen.

Wir nutzen nur offizielle Provider. Ein Provider bekommt Vollzugriff auf den Dienst, den er verwaltet. Wir setzen deshalb nur Provider ein, die der Hersteller selbst anbietet (siehe Grundsätze). Darum verwalten wir zum Beispiel Netcup und Proxmox nicht mit Terraform, obwohl es dafür Provider von Dritten gibt.

Der State liegt unverschlüsselt im Repo

terraform.tfstate liegt in jedem der beiden Ordner unverschlüsselt im Repo. Darin stehen auch Secrets, die Terraform in Authentik anlegt oder ausliest, zum Beispiel die Client-Secrets der Apps.

Das ist eine bewusste Abwägung; eine gute Lösung gibt es dafür nicht:

  • Terraform kann den State nicht verschlüsseln. OpenTofu, eine Abspaltung von Terraform, könnte es; wir bleiben trotzdem bei Terraform, weil noch unklar ist, wohin sich OpenTofu entwickelt.
  • Den State nachträglich zu verschlüsseln, wäre Gefrickel. Werkzeuge wie git-crypt, die Dateien beim Committen verschlüsseln, müssten bei allen eingerichtet sein, sind fehleranfällig und können bei Fehlern trotzdem Klartext auf der Platte oder im Repo hinterlassen.
  • Ein Remote State verschiebt das Problem nur. Terraform kann den State auch bei einem Dienst ablegen statt im Repo; das macht jede Ausführung komplizierter, der State liegt dort genauso unverschlüsselt, und eine gute, günstige Lösung gibt es dafür nur bei den großen Cloud-Anbietern, die wir nicht nutzen.

Wer Zugriff auf das Repo hat, kann diese Secrets lesen; deshalb bleibt das Repo privat (siehe Codeberg).

Weiterlesen