INI in YAML umwandeln

Ein Fachverfahren, das ein Amt seit Jahren auf einem einzelnen Server betreibt, wird heute selten neu geschrieben — es wird containerisiert. Der Anlass ist meist eine der laufenden Digitalisierungsinitiativen in der öffentlichen Verwaltung: eine Migration in eine Landes- oder Bundescloud, ein IT-Dienstleister, der mehrere Kommunen auf dieselbe Plattform holt, oder schlicht der Zwang, weil der alte Server das Ende seiner Wartungslaufzeit erreicht hat. Was übrig bleibt, ist eine PHP.ini oder eine hausgemachte Konfigurationsdatei, über SSH händisch gepflegt, und ein neues Zuhause, das Helm-Values oder eine Ansible-Variablendatei erwartet.

Diese Umwandlung übernimmt genau diesen einen Schritt: aus Abschnitten werden oberste Schlüssel, aus Einrückung wird YAML-Struktur. Was sie nicht übernimmt, ist die Entscheidung, wie ein Wert wie On oder Off in der Zielumgebung gelesen werden soll — und genau darin liegt der Teil dieser Migration, der schiefgehen kann, ohne dass ein Fehler gemeldet wird.

INI-Dateien schreiben On und Off weit häufiger als true und false. Die php.ini tut es, viele Windows- und Linux-Dienste tun es, und ein Dutzend älterer deutscher Behördenanwendungen wurden gegen genau diese Konvention geschrieben. Der Leser dieser Umwandlung behandelt diese Wörter nicht als Wahrheitswerte, sie bleiben also Zeichenketten, und der Schreiber gibt sie unquotiert aus: engine: On.

Ob diese Zeile eine Zeichenkette oder ein Wahrheitswert ist, hängt davon ab, welches YAML der jeweilige Parser spricht. YAML 1.2 — die Version, die die Registry für dieses Format führt, und die Version, die der Parser hinter dieser Seite tatsächlich umsetzt — liest „On" als Zeichenkette. YAML 1.1 liest es als Wahrheitswert true, und PyYAML setzt YAML 1.1 um, womit auch Ansible und ein langer Schwanz an Python-Werkzeugen betroffen sind. Dasselbe gilt für yes, no, y und n.

Die Lösung ist Quotierung, und sie muss von Hand geschehen, weil der Umwandler nicht wissen kann, welche der On-Werte tatsächlich als Schalter gemeint waren. engine: "On" liefert in jedem Parser die Zeichenkette, engine: true liefert in jedem Parser den Wahrheitswert. Beide sind eindeutig unter 1.1 und 1.2, und genau das ist die einzige Eigenschaft, die hier zählt.

Es lohnt sich, diesen Durchgang bewusst zu machen, statt nur die Fehler zu beheben, die auffallen. Ein als Zeichenkette gelesener Wahrheitswert ist meist wahr im Sinne der Bedingung und schaltet also still etwas ein; eine als Bool gelesene Zeichenkette scheitert meist laut an einer Schemaprüfung. Die gefährliche Richtung ist die leise: eine Einstellung, die man deaktiviert hatte, kommt aktiviert zurück, und nichts schlägt fehl, bis etwas schiefläuft.

Die Typisierung passiert beim Lesen der INI, nicht beim Schreiben der YAML, die Entscheidung steht also schon fest, bevor der YAML-Schreiber überhaupt zum Zug kommt. Werte, die sich als endliche Zahl parsen lassen, werden zu Zahlen, true und false werden zu Wahrheitswerten, alles andere bleibt Zeichenkette.

Drei Fälle in einer typischen Konfiguration kommen dadurch verändert an. Eine Version, festgelegt als 1.0, wird zu 1. Ein Dateimodus, geschrieben als 0755, wird zu 755 — nicht derselbe Modus mehr. Eine hexadezimale Maske, geschrieben als 0x1F, wird zu 31. Werte mit angehängter Einheit sind sicher, 128M bleibt 128M und 30s bleibt 30s, ebenso Adressen wie 127.0.0.1 und Uhrzeiten wie 08:00, die sich alle nicht als einzelne Zahl parsen lassen.

Ein Kopf, geschrieben als [tool.pytest] oder [mail.smtp], wird zu genau einem Schlüssel mit exakt diesem Namen, nicht zu zwei Verschachtelungsebenen. Der Leser nimmt alles zwischen den Klammern als einen einzigen Namen, was die einzig vertretbare Lesart ist — in vielen INI-Dateien sind Abschnitts- und Schlüsselnamen voller Punkte, die Teil des Namens sind und keine Trennzeichen.

YAML akzeptiert einen solchen Schlüssel unquotiert, die Ausgabe ist also gültig und liest sich unauffällig. Sie ist aber nicht das, was eine Helm-Chart oder eine Ansible-Rolle erwartet, wo mail.smtp.host normalerweise drei Ebenen wären. Das Aufteilen ist ein manueller und bewusster Eingriff, denn dabei wird etwas entschieden, das die Ursprungsdatei nie ausgesprochen hat.

Konfigurationen, die aus einer Basisdatei und einer per Skript angehängten Umgebungsergänzung zusammengesetzt wurden, tragen denselben Abschnittskopf mitunter zweimal. Der Leser legt bei jedem Kopf einen neuen leeren Abschnitt an, nur das letzte Vorkommen überlebt also, und das frühere verschwindet ohne Meldung.

Das lohnt sich vor der Migration zu prüfen statt danach, denn das Ergebnis ist wohlgeformtes YAML, dem schlicht Einstellungen fehlen, und ein fehlender Schlüssel in einer Bereitstellung zeigt sich meist als still angewendeter Standardwert, nicht als Fehler. Nach doppelten Köpfen in der INI-Datei suchen, bevor sie hierher kommt — dieselbe Regel gilt für einen innerhalb eines Abschnitts wiederholten Schlüssel.

YAML kann Kommentare, INI kann Kommentare, und keiner von ihnen übersteht diese Umwandlung. Kommentarzeilen werden beim Lesen übersprungen, und nichts schreibt sie zurück, sodass eine Datei, die zur Hälfte aus Erklärung bestand, als reine Werteliste ankommt.

Bei einer über Jahre gepflegten Konfiguration sind genau diese Kommentare das institutionelle Gedächtnis: der Hinweis, warum ein Timeout einmal angehoben wurde, der auskommentierte Block aus einer Störung, der nie entfernt wurde, das Kürzel neben einem Wert, den niemand anfassen will. Die ursprüngliche INI-Datei gehört in denselben Commit wie die YAML-Datei — das kostet nichts und ist die einzige Stelle, an der diese Begründung noch existiert.

Lesen und Schreiben sind beide gewöhnliches JavaScript auf dieser Seite, die Datei wird also nirgendwohin verschickt. Das gilt allgemein für die Datenumwandlungen auf dieser Website, und bei diesem Paar zahlt es sich besonders aus: Die INI-Datei, die von einem alten Server wegzieht, ist sehr oft genau die Datei, in der das Datenbankpasswort, die SMTP-Zugangsdaten und die API-Schlüssel stehen.

Die kostenlose Grenze liegt bei 100 MB, was keine Konfigurationsdatei je annähernd erreicht. Praktisch ist die Umwandlung sofort abgeschlossen, und das Einzige, was sich anschließend Zeit zu nehmen lohnt, ist das Lesen der Ausgabe — denn in dem Moment, in dem diese Geheimnisse in einer YAML-Datei in einem Repository liegen, stehen sie dauerhaft in dessen Historie, und das ist eine Entscheidung, die vor dem Commit getroffen werden sollte, nicht danach.

Liest die Anwendung weiterhin INI und wird das auch tun, ist die Umwandlung reiner Aufwand. YAML bringt Verschachtelung, Listen, Kommentare im Review und ein Lint-Werkzeug, und nichts davon hilft einem Programm, dessen Parser Abschnitte und Gleichheitszeichen erwartet. Die Migration lohnt sich, wenn die Konfiguration tatsächlich in ein System zieht, das YAML nativ liest — nicht schon, weil die Datei alt aussieht.

Der zweite ehrliche Grund innezuhalten ist die Größe. Eine Datei mit drei Abschnitten und zwanzig Schlüsseln ist schneller von Hand in die Zielstruktur übertragen als konvertiert und anschließend umgeformt, und beim Abtippen liest man jeden Wert einmal bewusst. Der Konverter lohnt sich, wenn die Datei groß genug ist, dass ein Lesen von Hand fehleranfällig wird.

Das Ergebnis ist ein vollständiges YAML-Dokument, kein Bruchstück. Diese Unterscheidung zählt, wenn das Ziel eine Values-Datei oder eine Variablensammlung ist, denn meist soll das ganze Dokument noch eine Ebene tiefer unter einem eigenen Schlüssel eingehängt werden, und es ist einfacher, ein bekanntermaßen korrektes Dokument einzurücken, als über ein Fragment nachzudenken.

Kein Format nutzt Tabulatoren zur Einrückung — YAML verbietet das, und ein Umwandler, der sie ausgäbe, würde eine Datei erzeugen, die kein Parser annimmt. Die Ausgabe hier verwendet durchgehend Leerzeichen, zwei je Ebene, in der Konvention, die jedes YAML-Werkzeug und jeder Linter erwartet.

Eine Migration betrifft selten eine einzelne Datei. Ein altes System hat meist eine Hauptkonfiguration und mehrere umgebungsspezifische Varianten — eine für die Entwicklung, eine für die Abnahme, eine für den Produktivbetrieb —, und alle sollen am Ende als YAML vorliegen. Bis zu hundert Dateien lassen sich hier gemeinsam ablegen, jede wird für sich gelesen und geschrieben, und das Ergebnis kommt als eine einzige ZIP-Datei zurück, statt jede Datei einzeln hochladen und wieder herunterladen zu müssen.

Weil die Umwandlung im Browser läuft, gibt es dabei keine Warteschlange und kein Tageskontingent, das für Server-Umwandlungen gälte — der Vorgang ist so schnell abgeschlossen, wie das eigene Gerät die Dateien lesen kann. Sinnvoll ist trotzdem, jede Datei nach dem Umwandeln kurz zu überfliegen und nicht blind dem Stapel zu vertrauen: Ein doppelter Abschnittskopf oder ein On-Wert fällt bei zwanzig Dateien leichter durch als bei einer.