Ich habe einmal einen Deploy ausgeliefert, der einen Dienst an die Version angeheftet hat 1.1 Als die Konfigurationsdatei deutlich sagte 1.10drohen Kein Tippfehler. Kein schlechter Fund und Ersetzen. Die YAML-Datei, die ich viermal gelesen hatte, sagte:
image_tag: 1.10
Und der Parser gab meinem Deploy-Skript die Nummer 1.1drohen weil 1.10 ist keine Versionszeichenfolge für YAML - es ist eine literal schwimmenund Schwimmer bleiben nicht nach Null. Zehn wird eins-Punkt-Eins. Die Datei war zu 100% gültig. Der Linter war glücklich. CI war grün. Der falsche Behälter ging aus.
Das ist das, was Ihnen niemand über die YAML-Validierung erzählt: "Gültig" ist nicht gleich "korrigierend". Ein Syntax-Checker, der nur Ja / Nein beantwortet, beantwortet die einfache Frage. Die schwierige Frage - die, die tatsächlich kaputt geht - ist Was hat sich aus meinem YAML verwandelt? Da YAML kein Konfigurationsformat ist, ist es eine Typ-Inferenz-Engine, die ein Konfigurationsformat trägt, und es trifft Entscheidungen über Ihre Daten, die Sie nie gebeten haben.
der YAML-Validator Auf toolz.dev beantwortet beide Fragen. Es wird Ihnen mitgeteilt, ob das Dokument analysiert wird, und zeigt Ihnen dann das analysierte Ergebnis als JSON - die tatsächliche Datenstruktur, die Ihr Tooling erhält. Diese zweite Hälfte hätte mich gerettet. "image_tag": 1.1 Im Ausgabefenster ist es nicht möglich, falsch zu lesen.
tl; dr: Füge deinen Yaml in die YAML-Validator und lies die JSON-Ausgabe, nicht nur das grüne Häkchen. Hier zeigt sich Typzwang:
1.10→1.1,0123→123, Unnotierte Werte werden lautlos zu Zahlen, Booleschen Werten oder NULL. Es läuft auf JS-YAML (YAML 1.2) vollständig in Ihrem Browser, sodass Kubernetes Secrets und Datenbankanmeldeinformationen Ihren Computer niemals verlassen. Zitieren Sie alles, was eine Zeichenfolge bleiben muss. Wenn Sie das Ergebnis mit einer JSON-Konfiguration vergleichen müssen, wird die JSON-Formater und json diff von dort abholen.
Was prüft ein YAML-Validator eigentlich?
zwei verschiedene Dinge, und es lohnt sich, sie zu trennen, weil sie unterschiedlich scheitern.
Syntaxvalidierung Fragen: Kann dieser Text überhaupt analysiert werden? Registerkarten, in denen Leerzeichen dazugehören, ein fehlendes Leerzeichen nach einem Doppelpunkt, ein Blockskalar, dessen Körper nicht eingerückt ist, ein nicht geschlossenes Zitat. Das sind schreiend Fehler. Ihr Parser wirft, Ihre Pipeline wird rot, Sie beheben es in zwei Minuten. Ärgerlich, nicht gefährlich.
Semantische Inspektion fragt: Was hat es analysiert? in? Hier leben die leisen Ausfälle. Das Dokument ist gültig. Die Pipeline ist grün. Der Wert ist einfach nicht das, was Sie dachten, Sie haben geschrieben. Niemand findet es heraus, bis sich die Produktion seltsam verhält, und bis dahin schaut sich niemand in die Konfigurationsdatei, weil die Konfigurationsdatei "fein" ist.
Die meisten Online-YAML-Checker machen nur den ersten. Der Toolz.dev-Validator führt den ersten aus und gibt Ihnen dann das zweite - das analysierte Dokument, das als JSON gerendert wird, direkt neben Ihrer Eingabe. Gewöhnen Sie sich an, diesen Bereich zu lesen. Es ist der Unterschied zwischen "die Datei ist gut ausgebildet" und "die Datei bedeutet, was ich meinte".
Welche YAML-Fehler brechen tatsächlich Builds?
Hier zeigt sich wirklich, wie viel von meinem Leben mich gekostet hat. Jedes Verhalten unten habe ich überprüft js-yaml 4, der der Parser ist, läuft der Toolz.dev Validator und der implementiert die YAML 1.2 Spez.
1. Registerkarten. Immer Tabs.
YAML verbietet die Tabulatorzeichen für Einrückungen. nicht "entmutigt" - Verbote. Die Spezifikation ist explizit und die Fehlermeldung ist erfrischend direkt:
tab characters must not be used in indentation
Der Grund, warum dies immer wieder geschieht, ist, dass Registerkarten unsichtbar sind. Ihr Editor zeigt Ihnen eine gut ausgerichtete Datei, der Parser sieht einen Steuerzeichen. Beheben Sie es an der Quelle: Stellen Sie Ihren Editor so ein, dass Leerzeichen eingefügt werden, und aktivieren Sie "Whitespace" für YAML-Dateien. Zwei Räume pro Ebene, die die Konvention ist, die jedes große YAML-Ökosystem besiegt hat.
2. Duplizieren Sie die Schlüssel
database:
host: localhost
port: 5432
host: production-db.example.com
host erscheint zweimal. Was passiert? Es hängt ganz von Ihrem Parser ab, der ein schrecklicher Satz ist, über ein Konfigurationsformat zu schreiben.
js-yaml Würfe: duplicated mapping keydrohen gut Das ist das gewünschte Verhalten, und das zeigt Ihnen der Toolz.dev-Validator. Aber Pyyaml - das ist es, was Ansible und viele Python-Tools sitzen - still nimmt das letze Wert und geht weiter. Keine Warnung. Ihr Datenbankhost ist jetzt das letzte Duplikat, das Sie in einer langen Datei, die Sie schlecht zusammengeführt haben, dreihundert Zeilen von der Stelle entfernt sind, an der Sie suchen.
Dies ist das beste Argument für die Ausführung von Konfigurationen über einen strengen Validator, auch wenn Ihr Produktionstools sie akzeptiert. ein Validator, der strenger Dann ist Ihre Laufzeit ein Validator, der Fehler findet.
3. Typ Zwang - der, der mich erwischt hat
YAML leitet Typen aus nicht zitierten Skalaren ab. Es ist sehr zuversichtlich und es ist oft falsch in Ihrer Absicht:
| du schreibst | du meintest | YAML 1.2 gibt Ihnen |
|---|---|---|
version: 1.10 |
Die Zeichenfolge "1.10" | Der Schwimmer 1.1 |
pin: 0123 |
Die Zeichenfolge "0123" | die ganze Zahl 123 |
port: "8080" |
die Nummer 8080 | die Schnur "8080" |
enabled: true |
boolesch | boolesch true - richtig |
value: |
Leere Zeichenfolge, vielleicht? | null |
value: ~ |
Eine Tilde | null |
das 0123 Row ist das, was ich auf Menschen Tattoo tätowieren kann. Postleitzahlen, PINs, Kontonummern, nullgepolsterte IDs - jede führende Null, die Sie aus einem bestimmten Grund geschrieben haben, wird gegessen. Zitiere sie.
Die Regel, die mich nie im Stich gelassen hat: Wenn der Wert ein Bezeichner, eine Version, ein Code oder etwas ist, das Sie niemals rechnen, setzen Sie es in Anführungszeichen. Ports und Replikate können frei bleiben. alles das nur Aussehen Numerisch sollte sein "quoted"drohen
4. Die versionsabhängigen Booleschen (a.k.a. das Norwegen-Problem)
Dieser ist wirklich berüchtigt und die Details sind wichtiger als das Mem.
in YAML 1.1, akzeptiert der Boolesche Typ yes, no, on, off, y, n, und ihre Kapitalisierungen zusätzlich zu true und falsedrohen so country: NO — Norwegens ISO-Ländercode — Parse als boolean treulosdrohen in YAML 1.2, die das nur bereinigt hat true und false sind Boolesche; NO ist nur die Schnur "NO"drohen
was bedeutet die gleiche Datei bedeutet verschiedene Dinge in verschiedenen Werkzeugen:
country: NO
feature_flag: on
- JS-YAML 4 (YAML 1.2 und was dieser Validator verwendet):
{"country": "NO", "feature_flag": "on"}- Saiten. - Pyyaml (Yaml 1.1):
{"country": False, "feature_flag": True}- Boolesche.
Gleiche Bytes. unterschiedliche Daten. Wenn Ihr CI einen Python-Linter über eine Konfiguration ausführt, die ein Knotendienst verwendet, sind zwei Parser über Ihre Datei anderer Meinung und keiner von ihnen ist falsch.
Dies ist auch der Ursprung von GitHub-Aktionen. on: Schlüssel, mit dem jeder Workflow beginnt, ist ein boolesch zu einem YAML 1.1-Parser, also Skripte, die in Python-Workflow-Dateien einen Schlüssel finden True anstelle ondrohen Zitat ("on":) ist legal und repariert es.
Der defensive Schritt ist der gleiche wie zuvor: zitifizierendrohen country: "NO" Mittel "NO" In jedem Parser, der jemals existiert hat.
5. Skalare Einbuchtung blockieren
description: |
This is not indented
der | (wörtlich) und > (gefaltete) Blockskalare benötigen ihren Inhalt relativ zum Schlüssel eingerückt. Uneingerückter Inhalt beendet den Block sofort und der Parser beginnt, Ihre Prosa als YAML-Schlüssel zu lesen, was Fehlermeldungen erzeugt, die anscheinend nichts mit dem tatsächlichen Fehler zu tun haben.
Wissenswertes über die Chomping-Indikatoren, während Sie hier sind: | hält eine einzelne nachlaufende Newline, |- streift es, |+ hält alle von ihnen. Wenn Sie einen privaten Schlüssel oder ein Skript einbetten und etwas Downstream über eine nachlaufende neue Zeile beschwert, ist dies Ihr Knopf.
6. nicht zitierte Sonderzeichen
Ein Doppelpunkt in einem nicht zitierten Wert beendet den Wert und startet einen neuen Schlüssel. Dies beißt in Fehlermeldungen und URLs:
message: Error: file not found # parse error
regex: [a-z]+ # parsed as a LIST, not a string
time: "22:22" # quote it — in YAML 1.1 this was base-60!
[, {, #, &, *, !, |, >, %, @ Zu Beginn eines Skalars bedeuten alle etwas. Zitat zuerst, stellen Sie später Fragen.
Wie validiere ich YAML auf toolz.dev?
- Öffne das YAML-Validatordrohen Kein Konto, kein Upload.
- Fügen Sie Ihr Dokument ein. Eine Helm-Wert-Datei, ein Docker-Compose, ein Workflow - was auch immer sich schlecht benimmt.
- Hit validieren. Fehler kommen mit genau zurück Linie und Spalte aus dem Parser plus der eigenen Grundzeichenfolge des Parsers (
bad indentation of a mapping entry,duplicated mapping key, und so weiter). - Lesen Sie den JSON-Ausgabebereich. Dies ist der Schritt, den die Leute überspringen und der eine zählt. Scannen Sie es nach den Werten, die Ihnen wichtig sind. ist
image_tagEine Zeichenfolge oder eine Zahl? Ist dieser Port zitiert? Ist ein leerer Wert geworden?null? - beheben, erneut validieren. Fehler können sich gegenseitig maskieren - der Parser stoppt beim ersten, von dem er sich nicht erholen kann, sodass das Beheben eines manchmal zwei weitere aufdeckt. Das ist normal, kein Zeichen, dass die Dinge immer schlimmer werden.
Eine bekannte Einschränkung, klar angegeben
Der Validator analysiert derzeit a Einzel-YAML-Dokumentdrohen Wenn Sie eine Multi-Dokument-Datei einfügen – mehrere Kubernetes-Manifeste, die durch getrennt werden --- In einer Datei, die ein äußerst häufiges Muster ist, wird berichtet:
expected a single document in the stream, but found more
Das ist der Parser, nicht die Datei wird kaputt. Die Problemumgehung heute besteht darin, jedes Dokument separat zu validieren: Füge alles über dem ---, prüfe es und fügen Sie dann das nächste Stück ein. Die Unterstützung von Multi-Dokumenten steht auf meiner Liste, gerade weil Kubernetes-Benutzer dies sofort erreichen, und ich möchte Ihnen lieber von der Lücke erzählen, als dass Sie sie mitten im Vorfall entdecken können.
YAML vs JSON: Wann soll ich welche verwenden?
YAML 1.2 ist eine strenge Obermenge von JSON - jedes gültige JSON-Dokument ist gültiges YAML, weshalb der Validator Ihnen JSON-Ausgabe überhaupt übergeben kann. Aber die Formate haben entgegengesetzte Persönlichkeiten.
| Zank | json | |
|---|---|---|
| Struktur definiert durch | Einkerbung (Whitespace-Significant) | Klammern und Klammern (explizit) |
| Kommentar | Ja (#) |
kein |
| Typus-Inferenz | Aggressiv – leitet Zahlen, Boolesche, Null, Daten ab | Keine - Anführungszeichen bedeuten immer Zeichenfolge |
| Mehrfachdokument | Ja (--- Trennzeichen) |
kein |
| Wiederverwendung | Anker (&), Aliase (*), Schlüssel zusammenführen (<<) |
keine |
| Fehlermodus | Stille Fehlinterpretation | Lauter Parse-Fehler |
| am besten bei | Dateien, die Menschen schreiben und bearbeiten | Datenmaschinenaustausch |
Der Handel ist real und geht in beide Richtungen. Die Lesbarkeit und Kommentare von Yaml sind genau der Grund, warum die Infrastrukturkonfiguration dort lebt - niemand möchte ein 400-zeiliges Kubernetes-Manifest in JSON ohne Kommentare beibehalten. Jsons totaler Mangel an Klugheit ist genau der Grund, warum APIs es verwenden: "1.10" ist "1.10" Und es gibt nichts zu besprechen.
Meine Regel: YAML für Dateien bearbeiten, JSON für Datenmaschinen übergeben. Und wenn eine YAML-Datei von einem Programm generiert wird, anstatt von einer Person getippt zu werden, ist dies ein Geruch - die maschinengenerierte Konfiguration bringt keinen der Vorteile von Yaml und all ihre Risiken.
Wenn Sie zwischen den beiden bewegen, JSON-zu-YAML-Konverter übernimmt die Transformation und JSON-Formater Wird die andere Seite aufräumen.
Was sind Anker und Aliase und sollte ich sie verwenden?
Mit YAML können Sie einen Block einmal definieren und wiederverwenden. ankern &, Referenz mit *, in eine Karte mit einfügen <<:
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
development:
<<: *defaults
database: myapp_dev
test:
<<: *defaults
database: myapp_test
beide development und test Kommen Sie mit dem Adapter, dem Host und dem Port zusammen, der zusammengeführt wird. Es ist wirklich nützlich, und JS-Yaml erledigt es - ich habe überprüft, dass die Zusammenführung korrekt aufgelöst wird.
Zwei Warnungen, aber.
zuerst, Zusammenführungsschlüssel sind eine YAML 1.1-Erweiterung, nicht Teil des YAML 1.2-Kerns. Unterstützung ist weit verbreitet, aber nicht universell, und - derjenige, der Menschen fängt - GitHub-Aktionen unterstützen sie nicht. Anker in einer Workflow-Datei machen nicht das, was Sie wollen. Überprüfen Sie Ihren Verbraucher, bevor Sie sich darauf stützen.
Zweitens machen Anker das Lesen einer Datei für die nächste Person schwieriger, und in der Konfiguration ist die nächste Person normalerweise um 2 Uhr morgens. Ich verwende sie für wirklich wiederholte Blöcke und niemals für Klugheit.
Während wir uns auf der gefährlichen Seite von YAML befinden: Das Format unterstützt benutzerdefinierte Tags, die einige Parser zum Erstellen beliebiger Objekte verwenden. yaml.load() war auf diese Weise bekanntermaßen ausnutzbar, weshalb yaml.safe_load() existiert und warum Sie es - immer - für jeden YAML verwenden sollten, der von außerhalb Ihres Teams kam. js-yaml load() In v4 ist standardmäßig sicher (es werden keine willkürlichen Typen erstellt), was hier eine Sache weniger ist, über die Sie sich Sorgen machen müssen.
Wie höre ich überhaupt auf, gebrochenes Yaml zu schreiben?
Prävention schlägt die Validierung und das meiste davon ist die Editorkonfiguration:
- Zwei Leerzeichen, niemals Tabs. Stellen Sie es pro Dateityp ein, damit Sie es nicht vergessen können.
- Aktivieren Sie das Rendern von Whitespace auf
.yml/.yamldrohen Wenn Sie den Tab sehen können, werden Sie den Tab nicht festlegen. - Installieren Sie einen YAML-Sprachserver. Die Echtzeit-Schema-Validierung gegen Kubernetes, GitHub-Aktionen und Docker-Compose-Schemas fängt eine ganze Fehlerklasse ab, die die Syntaxvalidierung nicht mit einem falsch geschriebenen Schlüssel gültig machen kann.
- Zitat standardmäßig im Zweifel. Die Kosten für ein unnötiges Angebot sind Null. Die Kosten für einen fehlenden sind ein Deploy.
- validieren, bevor Sie pushen, nicht nachdem CI fehlschlägt. Das Einfügen in einen Browser-Tab dauert acht Sekunden, eine fehlgeschlagene Pipeline dauert acht Minuten.
- Für Kubernetes die Schecks überlagern. Syntaxvalidierung fängt die Struktur;
kubectl apply --dry-run=clientFängt Schema. Sie finden verschiedene Fehler und Sie wollen beides.
Und die Gewohnheit, die die Dinge für mich verändert hat: Wenn ein Config-gesteuertes Deploy etwas unerklärliches tut, Schauen Sie sich die analysierte Ausgabe an, bevor Sie sich etwas anderes ansehen. nicht die Datei. die analysierte Ausgabe. Die Datei ist eine Geschichte darüber, was Sie gemeint haben. Die analysierte Ausgabe ist das, was tatsächlich passiert ist.
Das ist der gleiche Instinkt, der alles in meinem regiert API-Debug-Workflow - Lesen Sie die Daten, nicht den Code - und es gilt genauso gut für Konfigurationen wie für Antworten. Wenn Sie die breitere Tour von dem, was sonst noch in dieser Toolbox lebt, möchten, Anleitung für die Coding-Tools deckt es ab.
Häufig gestellte Fragen
Warum validiert mein YAML, aber immer noch meine Bereitstellung unterbrochen?
Denn Syntaxvalidität und semantische Korrektheit sind unterschiedliche Dinge. YAML leitet Typen aus nicht zitierten Werten ab 1.10 wird der Schwimmer 1.1, 0123 wird zur ganzen Zahl 123, und ein leerer Wert wird null — Alles in einem vollkommen gültigen Dokument. Lesen Sie die analysierte JSON-Ausgabe, nicht nur das Ergebnis für Pass / Fail, und geben Sie einen Wert an, der eine Zeichenfolge bleiben muss.
Warum verwandelt YAML meine Versionsnummer in eine andere Nummer?
1.10 ist ein Float-Literal für YAML, und Floats behalten keine nachlaufenden Nullen bei, sodass es sich auflöst 1.1drohen Jede Version, Build-Nummer oder nullgepolsterte Kennung muss angegeben werden: version: "1.10"drohen Dies ist einer der teuersten YAML-Fehler, da die Datei richtig aussieht und die Analyse erfolgreich ist.
Was ist das Norwegen-Problem in YAML?
In YAML 1.1 sind die Werte no, NO, off, und yes sind Boolesche, also Norwegens Ländercode NO parsen als falsedrohen YAML 1.2 hat dies behoben - nur true und false sind Boolesche - aber viele Tools (insbesondere Pyyaml, die Ansible verwendet) implementieren immer noch 1.1. Dieselbe Datei kann daher in verschiedenen Werkzeugen unterschiedliche Dinge bedeuten. Angabe des Wertes (country: "NO") macht es überall zu einer Schnur.
Kann ich Tabs für Einrückungen in YAML verwenden?
kein drohen Die YAML-Spezifikation verbietet die Registerkartenzeichen in Einrückung, und Parser lehnen sie mit einem Fehler wie "tabulatorzeichen" nicht in der Einrückung ab. & quot; Konfigurieren Sie Ihren Editor so, dass Leerzeichen für YAML-Dateien eingefügt werden - zwei Leerzeichen pro Ebene sind die Standardkonvention.
Unterstützt der Toolz.dev YAML-Validator Dateien mit mehreren Dokumenten?
Derzeit nicht. Es validiert ein einzelnes Dokument, sodass eine Datei mit mehreren Kubernetes-Manifesten durch getrennt ist --- Rückgabe "Erwartetes einzelnes Dokument im Stream" zurückgeben ". Validieren Sie jedes Dokument separat als Problemumgehung. Eine Multi-Dokument-Unterstützung ist geplant.
Sind doppelte Schlüssel in YAML erlaubt?
Die Spezifikation besagt, dass die Zuordnungsschlüssel eindeutig sein müssen, aber Parser sind in der Praxis nicht einverstanden. JS-YAML - von diesem Validator verwendet - löst einen Fehler "Duplizierter Mapping-Schlüssel" aus. Pyyaml behält den letzten Wert stillschweigend bei, was bedeutet, dass ein Duplikat Ihre Konfiguration ohne Warnung leise überschreiben kann. Wenn Sie Ihre Konfiguration über einen strengen Validator ausführen, wird dies abgefangen, bevor Ihre Laufzeit sie stillschweigend akzeptiert.
Ist es sicher, Kubernetes-Geheimnisse und -Anmeldeinformationen online zu validieren?
Mit dem Toolz.dev-Validator ja – das Parsen geschieht ganz in Ihrem Browser über JavaScript und nichts wird an einen Server übertragen. Sie können dies selbst bestätigen, indem Sie die Netzwerkregisterkarte Ihres Browsers öffnen, während Sie validieren und beobachten, dass keine Anfrage gestellt wird. Wenden Sie diese Prüfung auf ein beliebiges Online-Tool an, bevor Sie die Infrastrukturkonfiguration in sie einfügen.
Was ist der Unterschied zwischen .yml und .yaml?
Nichts funktionales - beide Erweiterungen werden von jedem YAML-Parser erkannt. Die offizielle Empfehlung ist .yaml;;; .yml Überlebt aus der Ära der Erweiterungen mit drei Zeichen und bleibt äußerst häufig (Docker Compose- und GitHub-Aktionen sind standardmäßig dazu verpflichtet). Wählen Sie eine aus und bleiben Sie innerhalb eines Projekts konsequent.
Wie konvertiere ich YAML in JSON?
Fügen Sie den YAML in den Validator ein und lesen Sie den Ausgabebereich - er rendert das analysierte Dokument als JSON, was die Konvertierung ist. Da YAML 1.2 eine Superset von JSON ist, hat jedes gültige YAML-Dokument ein JSON-Äquivalent, aber zuerst wird Typinferenz angewendet, also eine nicht zitierte 1.10 kommt als an 1.1 und 0123 als 123drohen Zitieren Sie diese Werte zuerst, wenn Sie sie als Zeichenfolgen erhalten müssen.
Wie validiere ich YAML gegen ein Schema?
Dieser Validator überprüft die Syntax und zeigt das analysierte Ergebnis an, validiert jedoch nicht gegen ein Schema. Dies ist eine separate Überprüfung, die bestätigt, dass Ihre Schlüssel und Werttypen mit dem von einem Tool wie Kubernetes oder GitHub Actions erwarteten übereinstimmen. Verwenden Sie für die Schemavalidierung einen YAML-Sprachserver in Ihrem Editor oder eine schemabewusste CLI wie z. kubeconform für Kubernetes oder kubectl apply --dry-run=clientdrohen Syntax und Schema-Validierung fangen verschiedene Fehler ab, führen Sie also beide aus.
