HCL, Datentypen und robuste Konfigurationen

HCL, Datentypen und robuste Konfigurationen

0:00 In den ersten beiden Modulen haben wir Infrastructure as Code eingeordnet und den Arbeitsablauf auf der Kommandozeile kennengelernt. Jetzt geht es um die Sprache selbst. HCL sieht auf den ersten Blick harmlos aus, fast wie eine Konfigurationsdatei mit ein paar Klammern. Doch hinter dieser Schlichtheit steckt eine ausgewachsene Sprache mit Typen, Ausdrücken und Funktionen.

0:20 Und genau die entscheidet, ob eine Konfiguration nur auf dem eigenen Rechner funktioniert oder ob ein ganzes Team sie gefahrlos benutzen kann. Unser Beispiel bleibt Saatplan, die interne Anwendung der Gärtnerei Lindenhof, mit Web, API und Datenbank in drei Containern. Am Ende dieses Moduls hat Saatplan eine Eingangskontrolle: Falsche Werte scheitern, bevor sie Schaden anrichten.

HCL, Datentypen und robuste Konfigurationen

0:42 Dieses Modul schließt den ersten Tag ab, und es verschiebt den Blickwinkel. Bisher haben wir gefragt, wie man Infrastruktur beschreibt. Jetzt fragen wir, wie man sie so beschreibt, dass andere sie benutzen können, ohne den Code zu lesen. Der Satz auf dieser Folie ist der Leitgedanke: Eine Konfiguration ist eine Schnittstelle.

1:01 Wir gehen von den Grundbausteinen der Sprache über Variablen und Typen bis zur Validierung und zu den Werten, die Terraform erst während der Ausführung erfährt. Am Ende steht eine Übung, die alles zusammenführt.

Blöcke, Referenzen und Ausdrücke

1:14 Beginnen wir beim Grundgerüst. Jede Konfiguration, ob drei Zeilen oder dreitausend, besteht aus denselben wenigen Bausteinen. Und einer davon hat eine Nebenwirkung, die man kennen sollte: Er legt ganz nebenbei die Reihenfolge fest, in der Terraform arbeitet. Stellen Sie sich einen Bauplan für ein Gewächshaus vor. Jedes Bauteil hat eine Art, einen Namen und eine Liste von Eigenschaften.

1:38 So ist auch HCL gebaut: Ein Block hat einen Typ, ein oder zwei Labels und einen Rumpf, in dem Argumente stehen, immer nach dem Muster Name gleich Ausdruck. Spannend wird es, wenn ein Argument auf ein anderes Bauteil verweist. Dann weiß Terraform: Das eine muss vor dem anderen stehen. Aus allen Verweisen zusammen entsteht der Abhängigkeitsgraph. Das ist eine elegante Idee, denn Sie beschreiben nur Zusammenhänge, und die Reihenfolge ergibt sich daraus von selbst.

2:05 Niemand muss eine Ablaufliste pflegen, die beim nächsten Umbau veraltet. Hier sehen Sie das Prinzip an Saatplan. Es gibt ein Netz namens saatplan-netz und einen Container für die Weboberfläche. Achten Sie auf die beiden markierten Stellen. Der Container nimmt die ID seines Images und die ID des Netzes, und zwar nicht als festen Text, sondern als Verweis auf die anderen Blöcke. Das hat zwei Folgen.

2:29 Erstens kann sich niemand vertippen, denn der Wert kommt direkt aus der Quelle. Zweitens legt Terraform Netz und Image zuerst an und erst dann den Container, obwohl diese Reihenfolge nirgends ausdrücklich steht. Genau das meinen wir mit impliziter Abhängigkeit: Der Verweis ist zugleich die Anweisung. Dieser Gegensatz ist einer der wichtigsten in der ganzen Sprache. Ein resource-Block sagt: Dieses Objekt gehört mir. Terraform legt es an, ändert es und löscht es auch wieder.

2:57 Ein data-Block sagt dagegen: Dieses Objekt gibt es schon, ich möchte nur etwas darüber wissen. Er liest Werte aus und ändert niemals etwas. Im Alltag ist das der Unterschied zwischen dem eigenen Beet und dem Nachbarbeet. Am eigenen dürfen Sie umgraben, beim Nachbarn schauen Sie nur, was dort wächst. Wenn also ein Netz von einem anderen Team betrieben wird, gehört es in einen data-Block. Sonst glaubt Terraform, es sei zuständig, und räumt es womöglich eines Tages ab.

Variablen, Locals und Outputs

3:26 Bisher standen alle Werte fest im Code. Das ist für ein erstes Beispiel in Ordnung, für eine Konfiguration im Team aber nicht. Es gibt drei Arten von Werten, jede mit einer klaren Aufgabe, und wer sie auseinanderhält, schreibt deutlich lesbarere Konfigurationen. Man kann sich das wie eine Küche vorstellen. Variablen sind die Zutaten, die von außen hereingereicht werden.

3:49 Locals sind das, was Sie auf dem Schneidbrett vorbereiten: ein benannter Zwischenwert, damit Sie denselben Ausdruck nicht fünfmal schreiben. Die Ressourcen sind das eigentliche Kochen, sie greifen auf beides zurück. Und Outputs sind der Teller, der den Raum verlässt, also das, was andere Konfigurationen oder Menschen von Ihrer Arbeit sehen. Wichtig ist die Richtung.

4:10 Werte fließen von links nach rechts, und nur Variablen und Outputs sind Teil der Schnittstelle. Locals bleiben Ihre private Angelegenheit und dürfen sich jederzeit ändern. Drei Dateien, drei Rollen. Die Variable umgebung beschreibt, wohin ausgerollt wird, und sie bringt gleich einen Typ und eine Beschreibung mit. Das ist keine Formalie, denn die Beschreibung ist die Dokumentation für alle, die die Konfiguration später benutzen.

4:36 Das Local baut aus der Umgebung ein Präfix für Namen, damit Testumgebung und Produktion sich nicht in die Quere kommen. Und der Output reicht den Namen des Web-Containers nach außen. Ein kleines Detail führt regelmäßig zu Verwirrung: Definiert werden Locals in einem Block namens locals, gelesen werden sie aber über local, in der Einzahl.

4:56 Und sie gelten nur im eigenen Modul. Terraform liest alle Dateien eines Verzeichnisses zusammen, es ist ihm also völlig egal, wie Sie sie aufteilen. Den Menschen ist es nicht egal. Der Style Guide schlägt deshalb eine feste Aufteilung vor, und der Gewinn liegt darin, dass jeder sofort weiß, wo er suchen muss. Wer eine neue Variable sucht, öffnet variables.tf, wer die Provider-Version wissen will, öffnet die Datei mit dem terraform-Block.

5:23 Saatplan nennt diese Datei versions.tf, auch das ist verbreitet. Bemerkenswert ist die alphabetische Sortierung bei Variablen und Outputs. Sie wirkt pedantisch, verhindert aber Streit darüber, wo etwas hingehört, und macht Unterschiede im Review leichter lesbar.

Typen und optionale Attribute

5:40 Eine Variable ohne Typ nimmt alles an. Das klingt großzügig, ist aber eine Einladung zu Fehlern, die erst spät auffallen. Mit einem Typ schreiben Sie fest, was Sie erwarten, und machen aus der Variablen einen Vertrag. Die Typen ordnen sich in vier Familien. Die primitiven Typen kennen Sie aus jeder Programmiersprache: Text, Zahl, Wahrheitswert.

6:01 Sammlungen fassen viele gleichartige Werte zusammen, etwa die Liste der Betriebsstandorte oder die Umgebungsvariablen eines Containers. Strukturierte Typen dagegen bündeln verschiedenartige Werte, wie die Einstellungen eines Containers mit Image, Port und Neustartverhalten. Bleibt any, der Platzhalter. Er ist verführerisch, weil man sich damit das Nachdenken über den Typ spart.

6:23 Die Dokumentation ist an dieser Stelle aber ungewöhnlich deutlich: Genau dafür soll man ihn nicht verwenden. Ein bewusst gewählter Typ ist die erste und billigste Prüfung, die es gibt. Hier sehen Sie, wie ein Vertrag mit Spielraum aussieht. Die Einstellungen des API-Containers sind ein Objekt. Image und Port sind Pflicht, denn ohne sie läuft nichts.

6:45 Neustartverhalten und Umgebungsvariablen sind dagegen optional und haben einen Standardwert. Das ist ein großer Komfortgewinn: Wer die Konfiguration benutzt, gibt nur an, was vom Normalfall abweicht. Ein Punkt verdient Aufmerksamkeit. Fehlt ein optionales Attribut oder wird es ausdrücklich auf null gesetzt, greift der Standardwert. Hat das Attribut keinen Standardwert, bleibt es null.

7:08 Wählen Sie die Standards also bewusst, denn sie sind die Entscheidung, die Sie stellvertretend für alle treffen, die nicht nachdenken.

Eingaben validieren

7:17 Ein Typ sagt, welche Art von Wert erlaubt ist, aber nicht, welcher Wert sinnvoll ist. Eine Zahl kann auch ein unmöglicher Port sein. Dafür gibt es Validierungen, und ihr Ziel ist schlicht: Ein falscher Wert soll am Eingang scheitern, nicht irgendwo später auf dem Docker-Host. Die Variable für den externen Port der Saatplan-API bekommt einen validation-Block.

7:39 Er besteht aus zwei Teilen: einer Bedingung, die wahr sein muss, und einer Fehlermeldung, falls sie es nicht ist. Hier verlangt die Bedingung einen Port zwischen 1024 und 65535, also außerhalb der privilegierten Ports. Das Muster ist einfach, und gerade deshalb lohnt es sich. Sie können einer Variablen übrigens mehrere solcher Blöcke geben, jeden mit eigener Meldung.

8:01 Das ist besser als eine einzige riesige Bedingung, denn dann sagt die Fehlermeldung genau, welche Regel verletzt wurde, und niemand muss raten, welcher Teil einer langen Verknüpfung schiefging. Warum lohnt sich dieser Aufwand? Weil der Zeitpunkt zählt. Die Prüfung läuft, bevor überhaupt ein Plan entsteht. Ein falscher Port erreicht den Docker-Host also nie, und es entsteht kein halbfertiger Zustand, den man aufräumen muss. Mindestens ebenso wichtig ist die Fehlermeldung.

8:32 Wer sie gut schreibt, erspart allen anderen den Blick in den Code. Seit Terraform 1.9 und OpenTofu 1.9 darf eine Bedingung auch andere Variablen einbeziehen, damit lassen sich Abhängigkeiten zwischen Eingaben prüfen. Und schließlich: Eine Variable ohne Standardwert ist Pflicht. Fehlt sie, fragt die Kommandozeile nach, statt still einen Wert anzunehmen. Das ist lästig, aber ehrlich.

8:56 Der erste Stolperstein ist gut gemeint: Ein bequemer Standardwert für etwas, das je Umgebung verschieden ist. Dann fällt nie auf, dass jemand die Angabe vergessen hat, und die Produktion läuft mit den Werten der Testumgebung. Der zweite betrifft die Grenzen der Prüfung. Sie sieht nur die Form eines Werts, nicht die Wirklichkeit. Ob ein Port auf dem Host noch frei ist, weiß sie nicht.

9:18 Der dritte ist eine Frage der Höflichkeit: Eine Meldung wie ungültiger Wert spart beim Schreiben Sekunden und kostet später Stunden. Und der vierte führt direkt ins nächste Kapitel: Hängt eine Prüfung an einem unbekannten Wert, verschiebt sie sich bis zum apply.

Funktionen, Bedingungen und unbekannte Werte

9:34 HCL kann rechnen: Bedingungen auswerten, Listen umformen, Daten in andere Formate bringen. Das macht Konfigurationen kompakt. Aber es gibt eine Grenze, die man verstehen muss, weil Terraform manche Werte erst erfährt, wenn es tatsächlich etwas anlegt. Drei Werkzeuge in einem einzigen locals-Block. Die Bedingung wählt das Neustartverhalten nach der Umgebung: In der Produktion soll ein Container immer wieder hochkommen, im Test nicht.

10:01 Der for-Ausdruck übersetzt zwischen zwei Welten. In der Variablen stehen die Umgebungsvariablen bequem als Map, der Docker-Provider erwartet aber Zeichenketten nach dem Muster Schlüssel gleich Wert. Der for-Ausdruck baut die eine Form aus der anderen. Und jsonencode erzeugt aus einer HCL-Struktur sauberes JSON. Das Muster dahinter: Halten Sie die Eingaben so, wie sie für Menschen bequem sind, und formen Sie sie erst dort um, wo eine Ressource etwas anderes verlangt.

10:29 Vier Punkte, die viel Rätselraten ersparen. Null bedeutet nicht leer, sondern nicht gesetzt. Ein Argument mit null verhält sich, als stünde es gar nicht da, und das ist praktisch für optionale Einstellungen. Dann die unbekannten Werte. Die ID eines neuen Containers vergibt erst Docker, im Plan steht deshalb known after apply. Alles, was an so einem Wert hängt, ist selbst unbekannt.

10:52 Für die meisten Argumente ist das kein Problem, für count und for each schon, denn dort muss Terraform schon beim Planen wissen, wie viele Objekte entstehen. Und zuletzt: JSON oder YAML nie als Text zusammenkleben. Eine vergessene Klammer findet man so erst im Betrieb.

Übung

11:09 Jetzt sind Sie dran. Saatplan bekommt eine Eingangskontrolle. Alles, was wir in diesem Modul besprochen haben, kommt in dieser Übung zusammen: Variablen, Typen, optionale Attribute und Validierungen. Das Ziel dieser Übung ist nicht, ein paar Variablen anzulegen. Es geht darum, die Eingaben einer Konfiguration als Vertrag zu denken.

11:30 Wer Saatplan ausrollt, soll an einer einzigen Stelle sehen, was er angeben muss, was er weglassen darf und was nicht erlaubt ist. Woran erkennen Sie, dass es geklappt hat? Ein Plan mit einem privilegierten Port oder mit einem Image aus einer fremden Registry bricht ab, und zwar mit Ihrer eigenen, verständlichen Meldung.

11:48 Mit gültigen Werten läuft er durch. Wer schneller fertig ist, kann eine Prüfung über zwei Variablen hinweg ergänzen: Web und API dürfen nicht denselben Port bekommen. Der Weg führt von außen nach innen. Zuerst holen Sie die festen Werte aus main.tf heraus und geben jeder Variablen einen Typ und eine Beschreibung. Dann fassen Sie die API-Einstellungen als Objekt und überlegen sich gut, welche Standardwerte wirklich für alle passen. Erst danach kommen die Validierungen.

12:17 Der vierte Schritt ist der wichtigste und wird oft übersprungen: Probieren Sie die falschen Werte tatsächlich aus und lesen Sie die Meldungen so, als kennten Sie den Code nicht. Zum Schluss Outputs ergänzen, terraform fmt und terraform validate laufen lassen. Damit endet der erste Tag. Im nächsten Modul geht es darum, wie man Ressourcen so modelliert, dass ein Plan nur ändert, was sich wirklich ändert.