JSON in YAML umwandeln

Ein Kubernetes-Cluster liefert seine Ressourcen als JSON zurück, wenn man sie über die API abfragt — ein Deployment, eine ConfigMap, eine Pipeline-Definition, die ein Tool exportiert hat. Ins Repository gehört davon aber die YAML-Fassung, weil jede Dokumentation, jedes Beispiel und jede Reviewer:in in diesem Format denkt.

Das betrifft nicht nur Kubernetes. GitHub Actions, GitLab CI und docker-compose erwarten dieselbe Einrückungsschreibweise, und ein Plattform-Team, das eine Pipeline aus einem älteren System herauslöst, bekommt am Ende fast immer erst JSON und muss es danach in das Format bringen, das im eigenen Repo Standard ist.

Seit der Spezifikation von 2009 gilt: Jedes gültige JSON-Dokument ist zugleich gültiges YAML. Die Umwandlung schreibt denselben Baum also nur in einer anderen Schreibweise neu, ohne Typ, Struktur oder einen einzigen Wert zu verändern.

Das macht diese Seite anders als die meisten Nachbarseiten hier. Es gibt keinen Datenverlust zu erklären und keine Rundung zu rechtfertigen. Was bleibt, sind Fragen dazu, wie das Ergebnis gelesen wird — und die sind wichtiger, als jede Datenverlust-Warnung es wäre.

Der YAML-1.2-Standard behandelt yes, no, on und off als gewöhnliche Zeichenketten, also schreibt der Konverter sie unquotiert. Ein YAML-1.1-Leser — und PyYAML, das hinter Ansible und einem Großteil der Python-Werkzeuge steckt, ist genau das — löst dieselben Wörter zu Wahrheitswerten auf. Aus dem String „no" wird beim Einlesen false.

Für ein deutschsprachiges Manifest ist das seltener ein Problem, als man annehmen könnte: „ja" und „nein" sind für keinen YAML-Parser reservierte Wörter, weder in Version 1.1 noch in 1.2. Die Falle klappt trotzdem regelmäßig zu, weil deutsche Teams ihre Feldnamen und Werte aus englischsprachigen Tutorials kopieren — enabled: yes, retry: no —, und genau diese kopierten Werte sind es, die beim nächsten Ansible-Lauf zu false statt zur erwarteten Zeichenkette werden.

Der Schreiber quotiert gezielt dort, wo die unquotierte Form etwas anderes bedeuten würde. Die Zeichenkette „1.0" bekommt Anführungszeichen, weil sie sonst als Zahl gelesen würde; „null" ebenso, weil das unquotierte Wort den Nullwert bezeichnet. Ein Wert, der mit einer Raute beginnt, wird quotiert, weil eine Raute sonst einen Kommentar einleitet.

Die Regel folgt konsequent YAML 1.2: Genau die Werte, die unter 1.2 ihre Bedeutung ändern würden, werden geschützt; die Werte, die nur unter 1.1 kippen — yes, no, on, off, und ein datumsförmiger String wie 2024-01-01 — bleiben bewusst unquotiert, weil sie nach dem aktuellen Standard einfache Zeichenketten sind.

Ein JSON-String kann keinen echten Zeilenumbruch enthalten, also steht ein eingebettetes Shell-Skript oder ein SQL-Statement als eine einzige, sehr lange Zeile mit \n an jeder Stelle, an der eigentlich eine neue Zeile beginnen sollte. Eine Änderung daran im Review zu erkennen, ist kaum möglich.

Der YAML-Schreiber setzt solche Werte als Block-Scalar: ein Pipe-Zeichen, danach der Text auf eigenen, eingerückten Zeilen mit den Umbrüchen an ihrem Platz. Ein zwölfzeiliges Entrypoint-Skript wird wieder zu zwölf Zeilen — für ein Manifest, das jemand im Team lesen und freigeben soll, ist das oft der größte einzelne Gewinn dieser Umwandlung.

Ein JSON-Array aus Objekten wird zur Liste mit Bindestrich, wie sie in jedem Kubernetes- und Actions-Beispiel steht: ein Strich, dahinter der erste Schlüssel, darunter eingerückt der Rest. Container, Steps, Volumes und Jobs kommen genau in der Form an, die auch die Dokumentation zeigt.

Für die Korrektheit ändert das nichts, wohl aber für das Review. Wer sechs Deployment-Schritte in YAML durchsieht, erkennt die Grenzen zwischen ihnen ohne geschweifte Klammern zu zählen — genau der Grund, warum sich das Ökosystem trotz der Einrückungsfallen für dieses Format entschieden hat.

JSON kennt keine Kommentare — die Grammatik in RFC 8259 sieht dafür schlicht keine Produktion vor, ein korrekter Parser hat also nichts zu akzeptieren. YAML erlaubt sie überall dort, wo eine Zeile mit einer Raute beginnen kann. Ein exportiertes Manifest nach YAML zu bringen, geht meistens gar nicht in erster Linie um die Syntax — es geht darum, endlich einen Ort zu haben, an dem steht, warum ein Wert so gesetzt ist.

Im frisch erzeugten Ergebnis steht noch nichts davon, weil auch die Quelle nichts hatte. Das Nachtragen ist die erste sinnvolle Bearbeitung, und die nützlichsten Kommentare beschreiben nie, was ein Feld ist, sondern warum die Replikenzahl drei beträgt, an welches andere Repository das Image-Tag gekoppelt ist, und was bricht, wenn das Timeout gesenkt wird.

YAML kennt Anker und Aliase, mit denen ein Block einmal definiert und an drei Stellen referenziert wird, und es kennt mehrere Dokumente in einer Datei, getrennt durch drei Bindestriche. Beides ist verbreitet — Compose-Dateien und Kubernetes-Bündel nutzen es regelmäßig —, und keines von beidem kann aus einer JSON-Quelle entstehen, weil JSON keine Möglichkeit hat, es auszudrücken.

Das erzeugte Manifest ist also korrekt und flach: Was im JSON wiederholt stand, steht auch im YAML wiederholt. Die Wiederholung nachträglich in einen Anker zu ziehen, ist eine manuelle Änderung, die sich nur lohnt, wenn sie wirklich echte Duplizierung beseitigt.

Der Schreiber übernimmt die Reihenfolge, in der die Schlüssel ankamen — apiVersion, kind und metadata stehen also weiter oben, statt alphabetisch sortiert zu werden. Weder JSON noch YAML definiert eine Bedeutung für die Reihenfolge von Schlüsseln, und viele Werkzeuge sortieren trotzdem frei, aber ein alphabetisiertes Manifest ist schwerer zu lesen und erzeugt bei jedem Diff unnötig viel Rauschen.

Das lohnt sich zu wissen, wenn das Ergebnis gegen eine bereits im Repository liegende Datei verglichen wird. Unterscheiden sich beide nur in der Reihenfolge, kam der Unterschied von dem, was das JSON erzeugt hat — eine aus dem Cluster gelesene Ressource liefert Felder in der Reihenfolge des API-Servers, nicht in der, in der sie einmal geschrieben wurden.

Die günstigste Prüfung ist die des Werkzeugs selbst: kubectl apply mit --dry-run=client, docker compose config oder der Linter der Actions-Datei. Jedes davon liest das Dokument und meldet die gefundene Struktur — das findet einen falsch platzierten Schlüssel schneller, als ihn im Editor zu suchen.

Die Prüfung, die das Quotierungsproblem findet, ist eine andere und muss bewusst gemacht werden: im umgewandelten Text nach unquotiertem yes, no, on, off und jedem unquotierten Datum suchen und für jeden Fall entscheiden, ob ein YAML-1.1-Leser ihn je zu Gesicht bekommt. Das dauert eine Minute und ist der einzige Teil dieser Umwandlung, vor dem kein Parser warnt.

Manche Werkzeuge, die eine bestehende Container-Landschaft inspizieren, geben ihre Erkenntnisse als JSON zurück, obwohl das Zielformat für eine lokale Entwicklungsumgebung eindeutig eine compose-Datei ist. Wer einen laufenden Stand auf diese Weise sichern oder an ein neues Teammitglied weitergeben will, steht damit vor derselben Umwandlung wie bei Kubernetes, nur mit Diensten, Volumes und Netzwerken statt mit Deployments und Services.

Die Struktur unterscheidet sich kaum: Auch hier werden Objektlisten zu Bindestrich-Listen, auch hier lohnt sich der Blick auf yes, no, on und off in den Umgebungsvariablen, weil gerade dort häufig Werte wie DEBUG=yes oder RESTART=no aus einer Kopiervorlage landen, ohne dass beim ersten Schreiben jemand an eine YAML-1.1-Umgebung gedacht hat.

Die Umwandlung läuft in diesem Tab. Der JSON-Parser stammt aus dem Browser selbst, und der YAML-Schreiber ist eine Bibliothek, die diese Seite nachlädt — es gibt also keine Anfrage, die das Dokument irgendwohin trägt, kein Konto und kein Tageslimit, und die freie Version nimmt bis zu 100 MB entgegen, weit mehr als jedes Manifest braucht.

Für dieses Publikum ist das keine abstrakte Zusicherung. Ein aus einem laufenden Cluster gelesenes Manifest trägt interne Hostnamen, Registry-Pfade, Service-Account-Namen und die Form der eigenen Infrastruktur, und in nicht wenigen deutschen IT-Abteilungen gilt das Einfügen solcher Inhalte in einen öffentlichen Web-Konverter als meldepflichtiger Vorfall. Hier gibt es nichts zu senden.