YAML bis JSON: Konfigurationen konvertieren, ohne den Verstand

Was eine Umrechnung von YAML in JSON tatsächlich bewirkt

YAML und JSON beschreiben die gleichen Formen – Karten, Listen, Zeichenfolgen, Zahlen, Boolesche Werte und Nullen – daher besteht die Konvertierung hauptsächlich darin, eine Syntax wie die andere neu zu serialisieren. Was sich ändert, ist die Oberfläche: Einrückungen werden zu geschweiften Klammern, Kommentare verschwinden, Anker werden zu Kopien und mehrzeilige Zeichenfolgen werden zu `\n`-Escapezeichen. Jede dieser Transformationen ist in einer wichtigen Weise verlustbehaftet, weshalb es sich lohnt, den Konvertierungsschritt bewusst durchzuführen und ihn nicht als nachträglichen Formatierungseinfall zu betrachten.

Der praktische Grund für die Konvertierung besteht darin, dass JSON das ist, was das nächste Werkzeug benötigt. Kubernetes akzeptiert YAML, aber `kubectl`, JQ-Pipelines, API-Aufrufe und JavaScript sprechen alle JSON komfortabler. Das einmalige Konvertieren ist besser als die parallele manuelle Bearbeitung zweier Formate.

Multi-Dokument YAML: das stille Problem des ersten Dokuments

Eine YAML-Datei kann mehrere durch `---` getrennte Dokumente enthalten. Die meisten Konverter geben stillschweigend das erste zurück und werfen den Rest weg – so wird ein Manifest-Bundle mit einem Deployment, einem Service und einer ConfigMap zu einem einzigen Objekt ohne Warnung. Bei einer korrekten Konvertierung wird entweder eine Reihe von Dokumenten ausgegeben oder Sie werden explizit gefragt, welches Dokument Sie möchten. Wenn ein Konverter keine solche Kontrolle bietet, verliert er Daten.

Fehler sollten auf eine Zeile und eine Spalte zeigen

Die Toleranz von YAML gegenüber Leerzeichen ist genau der Grund, warum kleine Fehler schwer zu finden sind. Tabulatoren sind zum Einrücken unzulässig, ein fehlender Doppelpunkt verwandelt eine Zuordnung in eine Zeichenfolge und doppelte Schlüssel werden von einigen Parsern akzeptiert und von anderen abgelehnt. Wenn eine Konvertierung fehlschlägt, benennt die einzige nützliche Meldung die Zeile und Spalte und zeigt den fehlerhaften Auszug:

                spec:
  containers:
	- name: web      # tab used for indentation
error: line 3, column 0 — tabs cannot be used for indentation
              

Doppelte Schlüssel sind der gefährliche Fall: YAML-Parser behalten üblicherweise den letzten Wert und sagen nichts. Wenn `replicas: 3` zweimal vorkommt, sieht das JSON, das Sie erhalten, vollkommen gültig aus – und die falsche Zahl.

Zitierregeln, die die Reise überdauern

JSON ist in Bezug auf Zeichenfolgen strenger als YAML, daher werden bei Konvertierungen leere Werte in Anführungszeichen gesetzt. Das ist normal, aber zwei YAML-Macken verursachen echte Fehler: `yes`, `no`, `on` und `off` sind boolesche Werte in YAML 1.1, aber Zeichenfolgen in der JSON-Semantik und führende Nullwerte wie Postleitzahlen und Telefonnummern verlieren ihre Null, wenn sie als Zahlen behandelt werden. Wenn ein Feld während der Konvertierung eine Zeichenfolge bleiben muss, geben Sie es in der Quelle an.

Führen Sie es lokal aus, insbesondere für Clusterkonfigurationen

Kubernetes-Manifeste enthalten routinemäßig Anmeldeinformationen in `Secret`-Objekten, Verbindungszeichenfolgen in ConfigMaps und Tokens in CI-Dateien. Wenn Sie diese in einen Webdienst einfügen, werden sie an einen Server weitergeleitet, den Sie nicht kontrollieren. Ein browserbasierter Konverter führt die Analyse und Serialisierung im selben Tab durch, den Sie gerade lesen, sodass nichts übertragen wird – und eine Seite, die auch bei abgeschaltetem Netzwerk weiter funktioniert, ist eher ein Beweis dafür als ein Versprechen.

Ein sinnvoller Workflow

1. Validieren Sie zuerst YAML und korrigieren Sie alle gemeldeten Zeilen, Spalten und Auszüge.
2. Wählen Sie aus, wie mit Dateien mit mehreren Dokumenten umgegangen werden soll – Array oder ein bestimmtes Dokument.
3. Konvertieren Sie mit Einrückungen, die Ihrem Codebasisstil entsprechen (2 oder 4 Leerzeichen), und sortieren Sie die Schlüssel, wenn Sie unterschiedliche Ausgaben haben.
4. Behalten Sie YAML als Quelle der Wahrheit in Git und behandeln Sie JSON als generiertes Artefakt; Kommentare leben nur im YAML.