Das Verhalten, das hier beißt, wird spezifiziert, nicht zufällig: das YAML 1.2-Spezifikation Definiert, wie ein nicht zitierter Skalar auf einen Typ aufgelöst wird.
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't eine Versionszeichenfolge zu YAML - it's a 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 Syntaxprüfer, der nur Ja/Nein beantwortet, beantwortet die einfache Frage Die schwierige Frage - die, die tatsächlich bricht, stellt sich - 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 sagt Ihnen, ob das Dokument analysiert wird, und dann zeigt es Ihnen das geparste Ergebnis als JSON an - die tatsächliche Datenstruktur, die Ihr Tooling erhalten wird 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-Prüfer machen nur den ersten Der Toolz.dev-Validator macht den ersten und gibt Ihnen dann den zweiten - das geparste Dokument, gerendert als JSON, direkt neben Ihrer Eingabe Gewöhnen Sie sich an, diesen Bereich zu lesen It's der Unterschied zwischen & quot; die Datei ist wohlgeformt" 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 Tabulatorzeichen für die Einrückung Nicht & quot; entmutigt" - verbietet 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 key. Gut. Das und #39; ist das Verhalten, das Sie wollen, und es und #39; zeigt, was Ihnen der Toolz.dev-Validator zeigen wird. Aber PyYAML - das ist es, worauf Ansible und viele Python-Tools setzen - nimmt stillschweigend die 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 Zeile ist die eine I & #39; d Tätowierung auf Personen Postleitzahlen, PINs, Kontonummern, null gepolsterte IDs - jede führende Null, die Sie aus einem bestimmten Grund geschrieben haben, wird gefressen Zitieren Sie 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 - Norwegen's ISO-Ländercode - Parsen als boolesch 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}- booleschen.
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-Wertedatei, eine Docker-Komposition, ein Workflow - was auch immer's haben sich falsch verhalten.
- 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 erholen kann't, so dass das Beheben eines manchmal zwei weitere offenbart That's normal, kein Zeichen, dass es schlimmer wird.
Eine bekannte Einschränkung, klar angegeben
Der Validator analysiert derzeit a Einzel-YAML-Dokument. Wenn Sie eine Datei mit mehreren Dokumenten einfügen - mehrere Kubernetes-Manifestationen getrennt durch --- 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 überhaupt JSON-Ausgaben übergeben kann Aber die Formate haben gegensätzliche Persönlichkeiten.
| Zank | json | |
|---|---|---|
| Struktur definiert durch | Einkerbung (Whitespace-Significant) | Klammern und Klammern (explizit) |
| Kommentar | Ja (#) |
kein |
| Typus-Inferenz | Aggressiv - lässt Zahlen, Booleans, Null, Datumsangaben folgen | Keine - Zitate 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 er geht in beide Richtungen YAML' s Lesbarkeit und Kommentare sind genau der Grund, warum Infrastrukturkonfiguration dort lebt - niemand möchte ein 400-Zeilen-Kubernetes-Manifest in JSON ohne Kommentare pflegen JSON's völliger Mangel an Cleverness 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 und nicht von einer Person eingegeben wird, erhält „das „#39;s. eine geruchs-maschinengenerierte Konfiguration erhält keine Vorteile von YAML's und alle seine 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 zusammengelegten Adapter, Host und Port heraus. It's wirklich nützlich, und js-yaml verarbeitet 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-ErweiterungNicht Teil des Kerns YAML 1.2. Unterstützung ist weit verbreitet, aber nicht universell, und - die, die 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 - auf jedem YAML verwenden sollten, das von außerhalb Ihres Teams kam. js-yaml's 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 - die Daten lesen, nicht den Code - und er gilt genauso gut für Konfigurationen wie für AntwortenWenn Sie den weiteren Rundgang durch das wünschen, was sonst noch in dieser Toolbox lebt, ist die 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 geparste JSON-Ausgabe, nicht nur das Pass/Fail-Ergebnis, und geben Sie jeden 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 false. YAML 1.2 hat das behoben - nur true und false Booleans sind - aber viele Tools (vor allem PyYAML, das Ansible verwendet) implementieren noch 1.1. Dieselbe Datei kann daher in verschiedenen Tools unterschiedliche Bedeutungen haben Angabe des Wertes (country: "NO") macht es überall zu einer Schnur.
Kann ich Tabs für Einrückungen in YAML verwenden?
Nr. Die YAML-Spezifikation verbietet Tabulatorzeichen in Einrückungen, und Parser lehnen sie mit einem Fehler wie & quot; Tabulatorzeichen dürfen nicht in Einrückungen verwendet werden. & quot; Konfigurieren Sie Ihren Editor, um Leerzeichen für YAML-Dateien einzufügen - 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?
In der Spezifikation heißt es, dass Zuordnungsschlüssel eindeutig sein müssen, aber Parser sind sich in der Praxis nicht einig. js-yaml - das dieser Validator verwendet - wirft einen & quot; duplizierten Zuordnungsschlüssel" Fehler. PyYAML behält den letzten Wert stillschweigend bei, was bedeutet, dass ein Duplikat Ihre Konfiguration ohne Vorwarnung stillschweigend überschreiben kann. Wenn Sie Ihre Konfiguration über einen strengen Validator ausführen, wird dies abgefangen, bevor Ihre Laufzeit es stillschweigend akzeptiert.
Ist es sicher, Kubernetes-Geheimnisse und -Anmeldeinformationen online zu validieren?
Mit dem Toolz.dev-Validator, ja - das Parsen geschieht komplett in Ihrem Browser über JavaScript und es wird nichts an irgendeinen Server übertragen, können Sie dies selbst bestätigen, indem Sie Ihren Browser öffnen' s Netzwerk-Tab, während Sie validieren und beobachten, dass keine Anfrage gestellt wird, wenden Sie dieselbe Prüfung auf ein beliebiges Online-Tool an, bevor Sie die Infrastrukturkonfiguration darin einfügen.
Was ist der Unterschied zwischen .yml und .yaml?
Nichts Funktionelles - beide Erweiterungen werden von jedem YAML-Parser erkannt Die offizielle Empfehlung lautet .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 das YAML in den Validator ein und lesen Sie den Ausgabebereich - es gibt das analysierte Dokument als JSON wieder, was die Konvertierung ist Da YAML 1.2 eine Obermenge von JSON ist, hat jedes gültige YAML-Dokument ein JSON-Äquivalent, aber zuerst wird eine Typinferenz angewendet, also ein nicht zitiertes 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 anhand eines Schemas - das ist eine separate Prüfung, die bestätigt, dass Ihre Schlüssel und Werttypen mit dem übereinstimmen, was ein Tool wie Kubernetes oder GitHub Actions erwartet Verwenden Sie zur 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.
