El comportamiento que muerde aquí se especifica, no accidental: el Especificación YAML 1.2 define cómo se resuelve un escalar sin comillas en un tipo.
Una vez envié una implementación que anclaba un servicio a la versión 1.1 Cuando el archivo de configuración dijo claramente 1.10. No es un error tipográfico. No es un mal hallazgo y reemplazo. El archivo YAML, que había leído cuatro veces, decía esto:
image_tag: 1.10
y el analizador le entregó mi script de implementación el número 1.1. porque 1.10 isn't una cadena de versión para YAML - it's a Flotador Literal, y las carrozas no siguen arrastrándose ceros. Diez se convierte en un solo punto. El archivo era 100% válido YAML. El linter estaba feliz. CI era verde. El contenedor equivocado se apagó.
Eso es lo que nadie te dice sobre la validación de YAML: "Válido" no es lo mismo que "Correcto". Un verificador de sintaxis que sólo responde sí/no responde a la pregunta fácil. La pregunta difícil, la que realmente se despliega, es ¿En qué se convirtió mi yaml? Debido a que YAML no es un formato de configuración, es un motor de inferencia de tipo que usa una ropa de formato de configuración, y toma decisiones sobre sus datos que nunca le pidió que tomara.
los Validador YAM en Toolz.dev responde ambas preguntas. Le indica si el documento se analiza y luego le muestra el resultado analizado como JSON, la estructura de datos real que recibirá su herramienta. Esa segunda mitad es lo que me habría salvado. "image_tag": 1.1 En el panel de salida es imposible de malinterpretar.
TL;Dr: Pega tu YAML en el Validador YAM y lee el Salida JSON, no solo la marca de verificación verde. Ahí es donde se muestra la coerción de tipo:
1.10→1.1,0123→123, valores no citados convirtiéndose en números, booleanos o nulos silenciosamente. Se ejecuta en JS-YAML (YAML 1.2) completamente en su navegador, por lo que los secretos de Kubernetes y las credenciales de la base de datos nunca abandonan su máquina. Cita cualquier cosa que deba permanecer como una cadena. Si necesita comparar el resultado con una configuración JSON, el Formateador JSON y Diferencia de JSON recoger desde allí.
¿Qué comprueba realmente un validador YAML?
Dos cosas diferentes, y vale la pena separarlas porque fallan de manera diferente.
Validación de sintaxis pregunta: ¿Se puede analizar este texto? Pestañas donde pertenecen los espacios, un espacio faltante después de dos puntos, un escalar de bloques cuyo cuerpo no está sangrado, una cita no cerrada. estos son estridente fracasos. Tus lanzamientos de parser, tu pipeline se pone rojo, lo arreglas en dos minutos. Molesto, no peligroso.
Inspección semántica pregunta: ¿Qué analizó? hacia el interior de¿? Aquí es donde viven los fracasos silenciosos. El documento es válido. La tubería es verde. El valor simplemente no es lo que pensabas que escribiste. Nadie se entera hasta que la producción se comporta de manera extraña, y para entonces nadie está mirando el archivo de configuración, porque el archivo de configuración está "bien".
La mayoría de los verificadores YAML en línea solo hacen el primero. El validador Toolz.dev hace el primero y luego le entrega el segundo: el documento analizado, representado como JSON, justo al lado de su entrada. Adquiera el hábito de leer ese panel. It's la diferencia entre "el archivo está bien formado" y "el archivo significa lo que quise decir."
¿Qué errores de YAML realmente se rompen?
Esto es lo que realmente aparece, clasificado por cuánto de mi vida me ha costado cada uno. Cada comportamiento a continuación lo verifiqué contra JS-YAML 4, que es el analizador que ejecuta Toolz.dev Validator y que implementa el YAL 1.2 Especificación
1. Pestañas. siempre pestañas.
YAML prohíbe los caracteres de pestaña para sangría. No "desalenta" - prohíbe. La especificación es explícita y el mensaje de error es refrescantemente directo:
tab characters must not be used in indentation
La razón por la que esto sigue sucediendo es que las pestañas son invisibles. Su editor le muestra un archivo bien alineado; el analizador ve un carácter de control. Arreglelo en la fuente: configure su editor para insertar espacios y active "Render whitepace" para archivos YAML. Dos espacios por nivel, que es la convención en la que se ha establecido cada ecosistema YAML.
2. Teclas duplicadas
database:
host: localhost
port: 5432
host: production-db.example.com
host aparece dos veces. ¿Qué pasa? Depende completamente de su analizador, que es una oración horrible para escribir sobre un formato de configuración.
JS-Yaml tira: duplicated mapping key. Bien. Eso & #39; es el comportamiento que desea, y eso & #39; es lo que le mostrará el validador Toolz.dev. Pero PyYAML, que es sobre lo que se asienta Ansible y muchas herramientas Python, toma el mantenerse valor y sigue adelante. Sin advertencia. Su host de base de datos ahora es lo que sea que diga el último duplicado, que en un archivo largo que se fusionó mal podría estar a trescientas líneas de donde está buscando.
Este es el mejor argumento para ejecutar configuraciones a través de un validador estricto, incluso cuando las herramientas de producción las aceptan. Un validador que más estricto que su tiempo de ejecución es un validador que encuentra errores.
3. Escribe coerción, la que me atrapó
YAML infiere tipos de escalares no citados. Es muy seguro y a menudo es incorrecto en su intención:
| tu escribiste | quisiste decir | YAML 1.2 te da |
|---|---|---|
version: 1.10 |
La cadena "1.10" | la carroza 1.1 |
pin: 0123 |
La cuerda "0123" | el entero 123 |
port: "8080" |
el numero 8080 | la cuerda "8080" |
enabled: true |
booleano | booleano true - corect |
value: |
¿Cuerda vacía, tal vez? | null |
value: ~ |
una tilda | null |
aquello 0123 la fila es el único tatuaje I'd en las personas. Códigos postales, PIN, números de cuenta, identificaciones con cero relleno: cada cero inicial que escribiste por una razón se come. Cítalos.
La regla que nunca me ha defraudado: Si el valor es un identificador, una versión, un código o cualquier cosa en la que nunca harías aritmética, ponlo entre comillas. Los puertos y los recuentos de réplicas pueden permanecer al descubierto. todo lo que simplemente acecharse numérico debe ser "quoted".
4. Los booleanos dependientes de la versión (también conocido como el problema de Noruega)
Este es genuinamente notorio, y los detalles importan más que el meme.
red YAM 1.1, el tipo booleano acepta yes, no, on, off, y, ny sus capitalizaciones, además de true y false. de esta manera country: NO - Noruega's Código de país ISO - analiza como booleano mentiroso. red YAL 1.2, que limpió esto, sólo true y false son booleanos; NO es solo la cuerda "NO".
lo que significa el mismo archivo significa diferentes cosas en diferentes herramientas:
country: NO
feature_flag: on
- js-yaml 4 (YAML 1.2, y lo que usa este validador):
{"country": "NO", "feature_flag": "on"}- cuerdas. - Pyyaml (Yaml 1.1):
{"country": False, "feature_flag": True}- booleanos.
mismos bytes. diferentes datos. Si su CI ejecuta un linter de Python sobre una configuración que consume un servicio de nodo, tiene dos analizadores que no están de acuerdo con su archivo y ninguno de ellos está mal.
Este es también el origen de las acciones de GitHub, más extrañas: la peculiaridad: la on: La clave con la que comienza cada flujo de trabajo es un booleano A un analizador YAML 1.1, por lo que los scripts que pedan en los archivos de flujo de trabajo en Python encuentran una clave llamada True en vez de on. citando ("on":) es legal y lo arregla.
El movimiento defensivo es el mismo que antes: Citarlo. country: "NO" dinero a pagar "NO" en cada analizador que haya existido alguna vez.
5. Bloquear sangría escalar
description: |
This is not indented
los | (literal) y > Los escalares de bloques (plegados) necesitan que su contenido se incorpore con relación a la clave. El contenido no sangrado finaliza el bloque inmediatamente y el analizador comienza a leer su prosa como claves YAML, lo que produce mensajes de error que parecen no tener nada que ver con el error real.
Vale la pena conocer los indicadores de masticación mientras estás aquí: | Mantiene una sola línea de avance, |- lo desnuda, |+ los guarda a todos. Si está incrustando una clave privada o un script y algo aguas abajo se queja de una nueva línea, esta es su perilla.
6. Caracteres especiales no citados
Un espacio-colono dentro de un valor no citado finaliza el valor y comienza una nueva clave. Esto muerde mensajes de error y 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!
[, {, #, &, *, !, |, >, %, @ Al comienzo de un escalar significan algo. Cite primero, haga preguntas después.
¿Cómo valide YAML en Toolz.dev?
- Abre el Validador YAM. Sin cuenta, sin carga.
- Pegue su documento. Un archivo de valores de Helm, una composición acoplable, un flujo de trabajo, lo que sea, se está portando mal.
- Presiona validar. Los errores vuelven con el exacto Línea y columna del analizador, más la cadena de razón del propio parser (
bad indentation of a mapping entry,duplicated mapping key, y así sucesivamente). - Lea el panel de salida JSON. Este es el paso que la gente salta y es el que importa. Escanea los valores que te interesan. es
image_tag¿Una cadena o un número? ¿Ese puerto está cotizado? ¿Se convirtió un valor vacío?null¿? - Arreglar, revalidar. Los errores pueden enmascararse entre sí: el analizador se detiene en el primero del que puede y #39;t se recupera, por lo que arreglar uno a veces revela dos más. Eso ' es normal, no es una señal de que las cosas están empeorando.
Una limitación conocida, claramente
El validador actualmente analiza un Documento YAM único. Si pega un archivo de múltiples documentos, varios manifiestos de Kubernetes separados por --- en un archivo, que es un patrón extremadamente común, informará:
expected a single document in the stream, but found more
Ese es el analizador correcto, no el archivo que se está rompiendo. La solución actual es validar cada documento por separado: pegar todo lo que está encima de la ---, compruébalo, luego pega el siguiente trozo. El soporte de documentos múltiples está en mi lista precisamente porque los usuarios de Kubernetes lo golpean de inmediato, y prefiero informarle sobre la brecha que dejar que la descubra a mitad del incidente.
YAM vs JSON: ¿Cuándo debo usar cuál?
YAML 1.2 es un superconjunto estricto de JSON: cada documento JSON válido es YAML válido, razón por la cual el validador puede entregarle la salida JSON. Pero los formatos tienen personalidades opuestas.
| hablar con tachuelas | JISON | |
|---|---|---|
| estructura definida por | Sangría (espacio en blanco-significativo) | Abrazaderas y soportes (explícito) |
| comentarios | Sí (#) |
prohibido |
| Tipo de inferencia | Agresivo: infiere números, booleanos, nulo, fechas | Ninguno - las comillas significan cadena, siempre |
| multipliego | Sí (--- separador) |
prohibido |
| reutilizar | anclas (&), alias (*), combinar claves (<<) |
nadie |
| Modo de falla | mala interpretación silenciosa | Error de análisis fuerte |
| mejor en | Archivos que los humanos escriben y editan | Intercambio de máquinas de |
El comercio es real y va en ambos sentidos. YAML' La legibilidad y los comentarios son exactamente la razón por la que la configuración de infraestructura vive allí: nadie quiere mantener un manifiesto de Kubernetes de 400 líneas en JSON sin comentarios. JSON' La total falta de inteligencia es exactamente la razón por la que las API lo utilizan: "1.10" es "1.10" Y no hay nada que discutir.
mi regla: YAML para archivos de personas Editar, JSON para máquinas de datos pasan. Y cuando un archivo YAML es generado por un programa en lugar de escrito por una persona, esa configuración generada por máquina no obtiene ninguno de los beneficios de YAML' y todos sus riesgos.
Si te mueves entre los dos, el Convertidor JSON a YAML maneja la transformación, y la Formateador JSON Se ordenará el otro lado.
¿Qué son los anclajes y alias, y debo usarlos?
YAML te permite definir un bloque una vez y reutilizarlo. anclar con &, referencia con *, fusionar en un mapa con <<:
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
development:
<<: *defaults
database: myapp_dev
test:
<<: *defaults
database: myapp_test
a la vez development y test salga con el adaptador, el host y el puerto fusionados. It' es realmente útil y js-yaml lo maneja; verifiqué que la combinación se resuelve correctamente.
Sin embargo, dos advertencias.
primero, Las claves de combinación son una extensión YAML 1.1, no forma parte del núcleo YAML 1.2. El soporte está muy extendido pero no es universal y, el que atrapa a la gente, Las acciones de GitHub no las apoyan. Los anclajes en un archivo de flujo de trabajo no harán lo que quieras. Revise a su consumidor antes de apoyarse en esto.
En segundo lugar, las anclas hacen que un archivo sea más difícil de leer para la siguiente persona, y en la configuración, la siguiente persona suele ser usted a las 2 a. m. Los uso para bloques realmente repetidos y nunca para la ingenio.
Mientras estamos en el lado peligroso de YAML: el formato admite etiquetas personalizadas que algunos analizadores usan para construir objetos arbitrarios. yaml.load() fue famosamente explotable de esta manera, por eso yaml.safe_load() existe y por qué deberías usarlo, siempre, en cualquier YAML que venga de fuera de tu equipo. js-yaml's load() En V4 es seguro por defecto (no construirá tipos arbitrarios), lo cual es una cosa menos de qué preocuparse aquí.
¿Cómo dejo de escribir Broken Yaml en primer lugar?
Prevención supera la validación, y la mayor parte es la configuración del editor:
- Dos espacios, nunca pestañas. Configúralo por tipo de archivo para que no puedas olvidar.
- Activar la representación de espacios en blanco en
.yml/.yaml. Si puede ver la pestaña, no confirmará la pestaña. - Instale un servidor de idioma YAML. La validación de esquema en tiempo real contra Kubernetes, acciones de GitHub y esquemas de Compose Docker detecta una clase completa de error que la validación de sintaxis no puede : YAML válida con una clave mal escrita.
- Cotizar por defecto en caso de duda. El costo de una cotización innecesaria es cero. El costo de uno que falta es una implementación.
- Valida antes de empujar, no después de que CI falla. Pegar en una pestaña del navegador toma ocho segundos; una canalización fallida tarda ocho minutos.
- Para Kubernetes, coloque los controles. Estructura de capturas de validación de sintaxis;
kubectl apply --dry-run=clientCaptura el esquema. Encuentran diferentes errores y quieres ambos.
Y el hábito que en realidad cambió las cosas para mí: cuando una implementación impulsada por la configuración hace algo inexplicable, Mire la salida analizada antes de mirar cualquier otra cosa. No el archivo. la salida analizada. El archivo es una historia sobre lo que quisiste decir. La salida analizada es lo que realmente sucedió.
Ese es el mismo instinto que gobierna todo en mi Flujo de trabajo de depuración de API - lea los datos, no el código - y se aplica tanto a las configuraciones como a las respuestas. Si desea un recorrido más amplio por lo que vive en esa caja de herramientas, el Guía de herramientas de codificación lo cubre.
Preguntas frecuentes
¿Por qué mi yaml valida pero aún rompe mi implementación?
Porque la validez de sintaxis y la corrección semántica son cosas diferentes. YAML infiere tipos de valores no cotizados, por lo que 1.10 se convierte en el flotador 1.1, 0123 se convierte en el entero 123, y un valor vacío se convierte en null - todo en un documento perfectamente válido. Lea la salida JSON analizada, no solo el resultado de aprobado/reprobado, y cite cualquier valor que deba permanecer en una cadena.
¿Por qué YAML convierte mi número de versión en un número diferente?
1.10 es un flotador literal a YAML, y los flotadores no conservan ceros al final, por lo que se resuelve a 1.1. Cualquier versión, número de compilación o identificador de relleno cero debe citarse: version: "1.10". Este es uno de los errores de YAML más caros porque el archivo se ve bien y el análisis tiene éxito.
¿Cuál es el problema de Noruega en YAML?
En YAML 1.1, los valores no, NO, offy yes son booleanos, por lo que el código de país de Noruega NO se analiza como false. YAML 1.2 solucionó esto - solo true y false son booleanos, pero muchas herramientas (en particular PyYAML, que utiliza Ansible) aún implementan 1.1. Por lo tanto, el mismo archivo puede significar cosas diferentes en diferentes herramientas. Citando el valor (country: "NO") lo convierte en una cadena en todas partes.
¿Puedo usar pestañas para sangría en YAML?
No. La especificación YAML prohíbe los caracteres de pestaña en la sangría y los analizadores los rechazan con un error como "los caracteres de pestaña no deben usarse en sangría." Configure su editor para insertar espacios para archivos YAML; dos espacios por nivel es la convención estándar.
¿El validador de Toolz.dev YAML admite archivos de múltiples documentos?
actualmente no. Valida un solo documento, por lo que un archivo que contiene varios manifiestos de Kubernetes separados por --- Devuelve "esperado un solo documento en la secuencia". Valida cada documento por separado como una solución alternativa. Se planea el soporte de documentos múltiples.
¿Se permiten claves duplicadas en YAML?
La especificación dice que las claves de mapeo deben ser únicas, pero los analizadores no están de acuerdo en la práctica. js-yaml, que utiliza este validador, arroja un " clave de mapeo duplicada" error. PyYAML mantiene silenciosamente el último valor, lo que significa que un duplicado puede anular silenciosamente su configuración sin previo aviso. Al ejecutar su configuración a través de un validador estricto, se detecta esto antes de que su tiempo de ejecución lo acepte silenciosamente.
¿Es seguro validar los secretos y credenciales de Kubernetes en línea?
Con el validador Toolz.dev, sí, el análisis se realiza completamente en su navegador a través de JavaScript y no se transmite nada a ningún servidor. Puede confirmarlo usted mismo abriendo la pestaña Red de su navegador ' mientras valida y observa que no se realiza ninguna solicitud. Aplique esa misma verificación a cualquier herramienta en línea antes de pegarle la configuración de infraestructura.
¿Cuál es la diferencia entre .yml y .yaml?
Nada funcional: cada analizador YAML reconoce ambas extensiones. La recomendación oficial es .yaml; .yml Sobrevive de la era de las extensiones de tres caracteres y sigue siendo extremadamente común (docker compone y github acciones ambas por defecto). Elija uno y manténgase constante dentro de un proyecto.
¿Cómo convierto YAML a JSON?
Pegue el YAML en el validador y lea el panel de salida; representa el documento analizado como JSON, que es la conversión. Debido a que YAML 1.2 es un superconjunto de JSON, cada documento YAML válido tiene un equivalente JSON, pero primero se aplica la inferencia de tipos, por lo que no se cita 1.10 llega como 1.1 y 0123 de 123. Cotice esos valores primero si los necesita conservados como cadenas.
¿Cómo valide YAML contra un esquema?
Este validador verifica la sintaxis y muestra el resultado analizado, pero no se valida con un esquema; es decir, una verificación separada que confirma que sus claves y tipos de valores coinciden con lo que espera una herramienta como Kubernetes o GitHub Actions. Para la validación de esquemas, utilice un servidor de idioma YAML en su editor o una CLI compatible con esquemas como kubeconform para kubernetes o kubectl apply --dry-run=client. La validación de sintaxis y esquema detecta diferentes errores, así que ejecute ambos.
