Validateur YAML : pourquoi valide YAML déploie toujours la mauvaise chose

Une fois, j'ai envoyé un déploiement qui a épinglé un service à la version 1.1 Lorsque le fichier de configuration a clairement indiqué 1.10. Pas une faute de frappe. Pas une mauvaise découverte et remplacement. Le fichier YAML, que j'avais lu quatre fois, disait ceci :

image_tag: 1.10

Et l'analyseur a remis le numéro à mon script de déploiement 1.1. parce que 1.10 N'est-ce pas une chaîne de version pour YAML - c'est un flotteur, et les flotteurs ne continuent pas à traîner les zéros. Dix devient un point. Le fichier était 100% valide YAML. La linter était heureuse. CI était vert. Le mauvais conteneur s'est éteint.

C'est la chose que personne ne vous dit sur la validation YAML : "Valide" n'est pas la même chose que "correct". Un vérificateur de syntaxe qui ne répond que oui/non répond à la question facile. La question difficile - celle qui casse réellement le déploiement - est En quoi mon Yaml s'est-il transformé ? Parce que YAML n'est pas un format de configuration, c'est un moteur d'inférence de type portant des vêtements de format de configuration, et il prend des décisions concernant vos données que vous ne lui avez jamais demandé de prendre.

le Validateur de YAML sur toolz.dev répond aux deux questions. Il vous indique si le document analyse, puis il vous montre le résultat analysé en JSON, la structure de données réelle que votre outillage recevra. Cette seconde mi-temps est ce qui m'aurait sauvé. "image_tag": 1.1 Dans le volet de sortie, il est impossible de mal interpréter.

tl;dr : Collez votre Yaml dans le Validateur de YAML et lisez le Sortie JSON, pas seulement la coche verte. C'est là que la coercition de type se montre : 1.10 → 1.1, 0123 → 123, les valeurs non cotées deviennent silencieusement des nombres, des booléens ou des valeurs nulles. Il s'exécute sur JS-YAML (YAML 1.2) entièrement dans votre navigateur, de sorte que les secrets de Kubernetes et les informations d'identification de la base de données ne quittent jamais votre machine. Citez tout ce qui doit rester une chaîne. Si vous devez comparer le résultat avec une configuration JSON, le Formateur JSON et Diff JSON Ramasser à partir de là.

Qu'est-ce qu'un validateur YAML vérifie réellement ?

Deux choses différentes, et cela vaut la peine de les séparer car ils échouent différemment.

Validation de la syntaxe Demande : ce texte peut-il être analysé ? Tabs où appartiennent les espaces, un espace manquant après un côlon, un bloc scalaire dont le corps n'est pas en retrait, un devis non fermé. Ce sont fort échecs. Votre analyseur jette, votre pipeline devient rouge, vous le réparez en deux minutes. Ennuyeux, pas dangereux.

Inspection sémantique demande : qu'est-ce qu'il a analysé dans? C'est là que vivent les échecs calmes. Le document est valide. Le pipeline est vert. La valeur n'est tout simplement pas ce que vous pensiez avoir écrit. Personne ne le découvre tant que la production ne se comporte pas de manière étrange, et à ce moment-là, personne ne regarde le fichier de configuration, car le fichier de configuration est "bien".

La plupart des vérificateurs de YAML en ligne ne font que le premier. Le validateur toolz.dev effectue le premier, puis vous remet le second - le document analysé, rendu sous forme de JSON, juste à côté de votre entrée. Prenez l'habitude de lire ce volet. C'est la différence entre "le fichier est bien formé" et "le fichier signifie ce que je voulais dire".

Quelles erreurs de YAML cassent réellement les builds ?

Voici ce qui se manifeste vraiment, classé par la part de ma vie qui m'a coûté chacun. Chaque comportement ci-dessous, j'ai vérifié JS-YAML 4, qui est l'analyseur que le validateur TOOLZ.DEV exécute et qui implémente le Yaml 1.2 Spéc.

1. Onglets. Toujours des onglets.

YAML interdit les caractères de l'onglet pour l'indentation. Pas "décourage" — interdit. La spécification est explicite et le message d'erreur est rafraîchissant :

tab characters must not be used in indentation

La raison pour laquelle cela continue de se produire est que les onglets sont invisibles. Votre éditeur vous montre un fichier bien aligné, l'analyseur voit un caractère de contrôle. Corrigez-le à la source : définissez votre éditeur pour insérer des espaces et activez "Render Whitespace" pour les fichiers YAML. Deux espaces par niveau, qui est la convention sur laquelle chaque écosystème majeur de YAML s'est installé.

2. Clé en double

database:
  host: localhost
  port: 5432
  host: production-db.example.com

host apparaît deux fois. Que se passe-t-il ? Cela dépend entièrement de votre analyseur, qui est une phrase horrible à écrire sur un format de configuration.

js-yaml jets: duplicated mapping key. bien. C'est le comportement que vous souhaitez, et c'est ce que le validateur Toolz.dev vous montrera. Mais Pyyaml - ce qui est ce que Ansible et beaucoup d'outils Python, reposent - prend silencieusement le dernier valeur et passe à autre chose. Pas d'avertissement. Votre hôte de base de données est désormais ce que le dernier doublon a dit, ce qui, dans un fichier long que vous avez mal fusionné, pourrait être à trois cents lignes de l'endroit où vous recherchez.

Il s'agit du meilleur argument pour exécuter des configurations via un validateur strict, même lorsque votre outil de production les accepte. Un validateur qui plus strict Votre exécution est un validateur qui trouve des bogues.

3. Type de coercition - celui qui m'a attiré

YAML déduit les types de scalaires non cotés. Il est très confiant et il est souvent faux de votre intention :

celui 0123 Row est celui que je tatouer sur les gens. Les codes postaux, les codes PIN, les numéros de compte, les identifiants sans indices de zéro - chaque zéro principal que vous avez écrit pour une raison est mangé. Citez-les.

La règle qui ne m'a jamais laissé tomber : Si la valeur est un identifiant, une version, un code ou tout ce que vous ne ferez jamais arithmétique, mettez-le entre guillemets. Les ports et les nombres de répliques peuvent rester nus. tout ce qui simplement apparence Le numérique doit être "quoted".

4. Les booléens dépendant de la version (alias le problème de la Norvège)

Celui-ci est vraiment notoire, et les détails comptent plus que le mème.

à Yaml 1.1, le type booléen accepte yes, no, on, off, y, n, et leurs capitalisations, en plus true et false. aussi country: NO — L'indicatif de pays ISO de la Norvège — Analyse comme booléen feint. à Yaml 1.2, qui a nettoyé cela, seulement true et false sont des booléens ; NO est juste la chaîne "NO".

ce qui signifie le même fichier signifie différentes choses dans différents outils:

country: NO
feature_flag: on

• JS-YAML 4 (YAML 1.2, et ce que ce validateur utilise) : {"country": "NO", "feature_flag": "on"} — Chaînes.
• Pyyam (YAML 1.1): {"country": False, "feature_flag": True} — Booléens.

Mêmes octets. Différentes données. Si votre CI exécute un python linter sur une configuration qu'un service de nœud consomme, vous avez deux analyseurs en désaccord sur votre fichier et aucun d'eux n'est erroné.

C'est aussi l'origine des actions GitHub, bizarrerie : le on: La clé que chaque workflow commence est un booléen à un analyseur YAML 1.1, donc les scripts qui linturent les fichiers de flux de travail dans Python, trouvent une clé appelée True au lieu de on. citation ("on":) est légal et le corrige.

Le mouvement défensif est le même qu'avant : citez-le. country: "NO" ressources "NO" dans chaque analyseur qui ait jamais existé.

5. Blocage de l'indentation scalaire

description: |
This is not indented

le | (littéral) et > (plié) Les scalaires de blocs ont besoin de leur contenu en retrait par rapport à la clé. Le contenu non encodé met immédiatement fin au bloc et l'analyseur commence à lire votre prose en tant que clés YAML, ce qui produit des messages d'erreur qui semblent n'avoir rien à voir avec l'erreur réelle.

Cela vaut la peine de connaître les indicateurs de mèche pendant que vous êtes ici : | conserve une nouvelle ligne de suivi, |- le déshabille, |+ les garde tous. Si vous intégrez une clé privée ou un script et que quelque chose en aval se plaint d'une nouvelle ligne de fin, c'est votre bouton.

6. Caractères spéciaux non cités

Un espace-points à l'intérieur d'une valeur non cotée termine la valeur et démarre une nouvelle clé. Cela mord dans les messages d'erreur et les URL :

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!

[, {, #, &, *, !, |, >, %, @ Au début d'un scalaire, tous signifient quelque chose. Citez d'abord, posez des questions plus tard.

Comment valider YAML sur toolz.dev ?

1. Ouvrez le Validateur de YAML. Pas de compte, pas de téléchargement.
2. Collez votre document. Un fichier de valeurs de barre, un docker-compose, un flux de travail, quel que soit le comportement erroné.
3. Hit Valider. Les erreurs reviennent avec l'exact Ligne et colonne à partir de l'analyseur, plus la chaîne de raison d'être de l'analyseur (bad indentation of a mapping entry, duplicated mapping key, et ainsi de suite).
4. Lisez le volet de sortie JSON. C'est le pas que les gens sautent et c'est celui qui compte. Scannez-le pour les valeurs qui vous intéressent. est image_tag Une chaîne ou un chiffre ? Ce port est-il coté ? Une valeur vide est-elle devenue null?
5. Correction, ré-validation. Les erreurs peuvent se masquer – l'analyseur s'arrête au premier dont il ne peut pas se remettre, donc en en réparer un en révèle parfois deux autres. C'est normal, pas un signe que les choses empirent.

Une limitation connue, clairement indiquée

Le validateur analyse actuellement un Document unique YAML. Si vous collez un fichier multi-documents, plusieurs manifestes Kubernetes sont séparés par --- Dans un fichier, ce qui est un modèle extrêmement courant, il rapportera :

expected a single document in the stream, but found more

C'est l'analyseur étant correct, pas le fichier est cassé. La solution de contournement aujourd'hui consiste à valider chaque document séparément : collez tout ce qui est au-dessus de la ---, vérifiez-le, puis collez le prochain morceau. La prise en charge multi-documents est sur ma liste précisément parce que les utilisateurs de Kubernetes s'en sortent immédiatement, et je vous parle plutôt de l'écart que de vous le laisser découvrir au milieu d'un incident.

YAML vs JSON : Quand dois-je utiliser lequel ?

YAML 1.2 est un sur-ensemble strict de JSON - chaque document JSON valide est YAML valide, c'est pourquoi le validateur peut vous remettre la sortie JSON. Mais les formats ont des personnalités opposées.

Le commerce est réel et il va dans les deux sens. La lisibilité et les commentaires de Yaml sont exactement la raison pour laquelle la configuration de l'infrastructure y habite - personne ne veut maintenir un manifeste Kubernetes de 400 lignes en JSON sans commentaires. Le manque total d'intelligence de JSON est la raison pour laquelle les API l'utilisent : "1.10" est "1.10" Et il n'y a rien à discuter.

Ma règle : YAML pour les fichiers que les gens modifient, JSON pour les machines de données passent. Et lorsqu'un fichier YAML est généré par un programme plutôt que par une personne, c'est une odeur - la configuration générée par la machine n'obtient aucun des avantages de YAML et de tous ses risques.

Si vous vous déplacez entre les deux, le Convertisseur JSON en YAML gère la transformation, et Formateur JSON Restituera l'autre côté.

Que sont les ancres et les alias, et dois-je les utiliser ?

YAML vous permet de définir une fois un bloc et de le réutiliser. mouiller avec &, référence avec *, fusionner dans une carte avec <<:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  <<: *defaults
  database: myapp_dev

test:
  <<: *defaults
  database: myapp_test

l'un et development et test Sortez avec l'adaptateur, l'hôte et le port fusionnés. C'est vraiment utile, et JS-YAML le gère - j'ai vérifié que la fusion se résout correctement.

Deux avertissements, cependant.

Premièrement, Les clés de fusion sont une extension YAML 1.1, ne fait pas partie du noyau YAML 1.2. Le soutien est répandu mais pas universel, et — celui qui attrape les gens — GitHub Actions ne les prend pas en charge. Les ancres dans un fichier de workflow ne feront pas ce que vous voulez. Vérifiez votre consommateur avant de vous appuyer sur ce point.

Deuxièmement, les ancres rendent un fichier plus difficile à lire pour la personne suivante, et dans la configuration, la personne suivante est généralement vous à 2 heures du matin. Je les utilise pour des blocs véritablement répétés et jamais pour l'intelligence.

Bien que nous soyons du côté dangereux de YAML : le format prend en charge les balises personnalisées que certains analyseurs utilisent pour construire des objets arbitraires. yaml.load() était réputé exploitable de cette façon, c'est pourquoi yaml.safe_load() existe et pourquoi vous devriez l'utiliser - toujours - sur n'importe quel YAML qui vient de l'extérieur de votre équipe. JS-YAML load() Dans la V4 est sécurisée par défaut (il ne construit pas de types arbitraires), ce qui est une chose de moins à s'inquiéter ici.

Comment puis-je arrêter d'écrire des Yamls cassés en premier lieu ?

La validation de la prévention des battants est la plus importante, la plupart d'entre elles sont la configuration de l'éditeur :

• Deux espaces, jamais des onglets. Définissez-le par type de fichier pour ne pas oublier.
• Activer le rendu des espaces blancs pour .yml/.yaml. Si vous pouvez voir l'onglet, vous ne validerez pas l'onglet.
• Installez un serveur de langues YAML. Validation de schéma en temps réel avec Kubernetes, Actions GitHub et schémas de composition de Docker attrape une classe entière d'erreurs que la validation de la syntaxe peut : valide YAML avec une clé mal orthographiée.
• Devis par défaut en cas de doute. Le coût d'un devis inutile est nul. Le coût d'un manque est un déploiement.
• Valider avant de pousser, pas après que CI a échoué. Le collage dans un onglet du navigateur prend huit secondes, un pipeline défaillant prend huit minutes.
• Pour Kubernetes, superposez les vérifications. La validation de la syntaxe capture la structure ; kubectl apply --dry-run=client Attrape le schéma. Ils trouvent différents bugs et vous voulez les deux.

Et l'habitude qui a réellement changé les choses pour moi : lorsqu'un déploiement basé sur une configuration fait quelque chose d'inexplicable, Regardez la sortie analysée avant de regarder autre chose. pas le fichier. la sortie analysée. Le fichier est une histoire sur ce que vous vouliez dire. La sortie analysée est ce qui s'est réellement passé.

C'est le même instinct qui régit tout dans mon Workflow de débogage de l'API — Lisez les données, pas le code — et cela s'applique aussi bien aux configurations qu'aux réponses. Si vous voulez une visite plus large de ce qui vit dans cette boîte à outils, le Guide des outils de codage le recouvre.

Questions fréquentes

Pourquoi mon YAML valide-t-il mais interrompt-il mon déploiement ?

Parce que la validité de la syntaxe et l'exactitude sémantique sont des choses différentes. YAML déduit les types de valeurs non indiquées, donc 1.10 devient le flotteur 1.1, 0123 devient l'entier 123, et une valeur vide devient null — Le tout dans un document parfaitement valide. Lisez la sortie JSON analysée, pas seulement le résultat de réussite/échec, et citez toute valeur qui doit conserver une chaîne.

Pourquoi YAML transforme-t-il mon numéro de version en un autre numéro ?

1.10 est un flotteur de flottement pour YAML, et les flotteurs ne conservent pas les zéros de fin, il se résout donc 1.1. Toute version, numéro de build ou identifiant à zéro doit être indiqué : version: "1.10". C'est l'une des erreurs de YAML les plus chères, car le fichier semble correct et la parse réussit.

Quel est le problème de la Norvège dans YAML ?

Dans YAML 1.1, les valeurs no, NO, off, et yes sont des booléens, donc l'indicatif du pays de la Norvège NO analyse comme false. YAML 1.2 a corrigé ce problème — uniquement true et false sont des booléens - mais de nombreux outils (notamment pyyaml, dont Ansible utilise) implémentent toujours la 1.1. Le même fichier peut donc signifier des choses différentes dans différents outils. Citation de la valeur (country: "NO") en fait une chaîne partout.

Puis-je utiliser des onglets pour l'indentation dans YAML ?

non . La spécification YAML interdit les caractères de l'onglet dans Indentation, et les analyseurs les rejettent avec une erreur comme "les caractères d'onglet ne doivent pas être utilisés dans Indentation." Configurez votre éditeur pour insérer des espaces pour les fichiers YAML - deux espaces par niveau correspondent à la convention standard.

Le validateur YAML de Toolz.dev prend-il en charge les fichiers multi-documents ?

Pas actuellement. Il valide un seul document, donc un fichier contenant plusieurs manifestes Kubernetes séparés par --- Retourne "attendu un seul document dans le flux." Validez chaque document séparément comme solution de contournement. Une prise en charge multi-documents est prévue.

Les clés en double sont-elles autorisées dans YAML ?

La spécification stipule que les clés de cartographie doivent être uniques, mais les analyseurs ne sont pas d'accord dans la pratique. js-yaml — que ce validateur utilise — génère une erreur de mappage "dupliquée". Pyyaml conserve silencieusement la dernière valeur, ce qui signifie qu'un doublon peut ignorer tranquillement votre configuration sans aucun avertissement. L'exécution de votre configuration via un validateur strict attrape ceci avant que votre exécution ne l'accepte silencieusement.

Est-il sûr de valider les secrets et les informations d'identification de Kubernetes ?

Avec le validateur Toolz.dev, oui, l'analyse se produit entièrement dans votre navigateur via JavaScript et rien n'est transmis à un serveur. Vous pouvez le confirmer vous-même en ouvrant l'onglet Réseau de votre navigateur pendant que vous validez et observez qu'aucune demande n'est effectuée. Appliquez cette même vérification à n'importe quel outil en ligne avant d'y coller la configuration de l'infrastructure.

Quelle est la différence entre .yml et .yaml ?

Rien de fonctionnel — les deux extensions sont reconnues par chaque analyseur YAML. La recommandation officielle est .yaml; .yml Survit à l'époque des extensions à trois caractères et reste extrêmement courant (Docker Compose et GitHub Actions, par défaut). Choisissez-en un et restez cohérent dans un projet.

Comment convertir YAML en JSON ?

Collez le YAML dans le validateur et lisez le volet de sortie - il rend le document analysé en JSON, qui est la conversion. Parce que YAML 1.2 est un sur-ensemble de JSON, chaque document YAML valide a un équivalent JSON, mais l'inférence de type est appliquée en premier, donc un non-coté 1.10 arrive comme 1.1 et 0123 comme 123. Citez ces valeurs en premier si vous avez besoin de les conserver en tant que chaînes.

Comment valider YAML par rapport à un schéma ?

Ce validateur vérifie la syntaxe et affiche le résultat analysé, mais il ne valide pas par rapport à un schéma, c'est-à-dire une vérification séparée confirmant que vos clés et vos types de valeur correspondent à ce qu'un outil comme Kubernetes ou GitHub Actions attend. Pour la validation de schéma, utilisez un serveur de langue YAML dans votre éditeur ou une CLI compatible avec les schémas, comme kubeconform Pour Kubernetes ou kubectl apply --dry-run=client. La validation de la syntaxe et du schéma attrape différents bogues, alors exécutez les deux.