Le comportement qui mord ici est spécifié, et non accidentel : le Spécification YAML 1.2 définit comment un scalaire non cité est résolu en un type.
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 is' ;t une chaîne de version vers YAML - it' ;s a 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 par oui/non répond à la question facile La question difficile - celle qui casse réellement se déploie - 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é comme JSON - la structure de données réelle que votre outillage recevra Cette seconde moitié 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 YAML en ligne ne font que le premier Le validateur Toolz.dev fait le premier et vous remet ensuite le second - le document analysé, rendu par JSON, juste à côté de votre entrée Prenez l'habitude de lire ce volet It' ; 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 d'onglet pour l'indentation Pas " ; décourage" ; - interdit La spécification est explicite, et le message d'erreur est rafraîchissant direct :
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 le & #39 ; c'est ce que le validateur Toolz.dev vous montrera. Mais PyYAML - sur quoi Ansible et de nombreux outils Python s'assoient - prend silencieusement le dessus 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. Tapez la coercition - celle qui m'a eu
YAML déduit les types de scalaires non cotés. Il est très confiant et il est souvent faux de votre intention :
| tu as écrit | tu voulais dire | Yaml 1.2 vous donne |
|---|---|---|
version: 1.10 |
La chaîne "1.10" ; | le flotteur 1.1 |
pin: 0123 |
La chaîne "0123" ; | l'entier 123 |
port: "8080" |
Le nombre 8080 | la ficelle "8080" |
enabled: true |
booléen | booléen true - correct |
value: |
Chaîne vide, peut-être ? | null |
value: ~ |
Un tilde | null |
celui 0123 row est celui I' ; d tatouage sur les gens Les codes postaux, les codes PIN, les numéros de compte, les identifiants sans rembourrage - chaque zéro non significatif 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 - Norvège' ; code pays ISO - 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"}- des cordes. - 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 ?
- Ouvrez le Validateur de YAML. Pas de compte, pas de téléchargement.
- Collez votre document. Un fichier de valeurs Helm, un docker-compose, un flux de travail - what' ; se comporte mal.
- 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). - 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_tagUne chaîne ou un chiffre ? Ce port est-il coté ? Une valeur vide est-elle devenuenull? - Correction, ré-validation. Les erreurs peuvent se masquer mutuellement - l'analyseur s'arrête au premier qu'il peut et au numéro 39 ; il s'en remet, donc en réparer un révèle parfois deux autres. That' ; c'est normal, ce n'est 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 séparés par --- dans un fichier, ce qui est un modèle extrêmement courant, il vous sera rapporté :
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.
| banane | JSON | |
|---|---|---|
| Structure définie par | Indentation (espace blanc significatif) | Accolades et supports (explicite) |
| observation | oui (#) |
non |
| Type d'inférence | Agressif - infère des chiffres, des booléens, null, des dates | Aucun - guillemets signifie chaîne, toujours |
| multidocuments | oui (--- séparateur) |
non |
| réutiliser | Ancres (&), alias (*), fusionner les clés (<<) |
nul |
| Mode de panne | Incorrecte silencieuse | Erreur d'analyse forte |
| le mieux à | Fichiers que les humains écrivent et modifient | Échange de machines de données |
Le commerce est réel et il va dans les deux sens YAML' ; la lisibilité et les commentaires de S sont exactement pourquoi la configuration de l'infrastructure y vit - personne ne veut maintenir un manifeste Kubernetes de 400 lignes dans JSON sans commentaires JSON' ; le manque total d'intelligence est exactement pourquoi 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 tapé par une personne, ce & #39 ; est une odeur - la configuration générée par machine ne reçoit aucun des avantages de YAML& #39 ; et 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. It' ; 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 faisant pas partie du noyau YAML 1.2. le soutien est ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ ´ 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 venait de l'extérieur de votre équipe. js-yaml' ;s 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=clientAttrape 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 config qu'aux réponses Si vous souhaitez une visite plus large de ce qui vit d'autre 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 indiquez toute valeur qui doit rester 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é cela - seulement true et false sont booléens - mais de nombreux outils (notamment PyYAML, qu'Ansible utilise) implémentent toujours 1.1. un même fichier peut donc signifier différentes choses dans différents outils Citant 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 d'onglet dans l'indentation et les analyseurs les rejettent avec une erreur telle que " ; les caractères d'onglet ne doivent pas être utilisés dans l'indentation." ; Configurez votre éditeur pour insérer des espaces pour les fichiers YAML - deux espaces par niveau sont 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 dit que les clés de mappage doivent être uniques, mais les analyseurs ne sont pas d'accord dans la pratique. js-yaml - que ce validateur utilise - lance une clé de mappage " ; dupliquée" ; erreur PyYAML conserve silencieusement la dernière valeur, ce qui signifie qu'un duplicata peut tranquillement annuler votre configuration sans aucun avertissement L'exécution de votre configuration via un validateur strict l'attrape avant que votre runtime 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 passe entièrement dans votre navigateur via JavaScript et rien n'est transmis à aucun serveur Vous pouvez le confirmer vous-même en ouvrant votre navigateur' ; s Onglet Réseau pendant que vous validez et observez qu'aucune requête 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é comme 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-cité 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 distincte confirmant que vos clés et vos types de valeurs correspondent à ce qu'attend un outil comme Kubernetes ou GitHub Actions Pour la validation du schéma, utilisez un serveur de langage YAML dans votre éditeur, ou une CLI compatible avec le schéma telle que 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.
