YAML en Kubernetes: 12 errores de configuración que rompen despliegues a las dos de la madrugada

YAML parece simpático hasta error dos espacios indentación tumba clusters producción madrugadas guardias porque Kubernetes cara humana infraestructura por defecto significa formato sensible whitespace editable bajo presión copy-paste foros chats plantillas incompletos. Sintaxis permite flexibilidades escalares comillas opcionales comentarios—which ayuda human pero confunde máquinas cuando off/no interpretadas boolean inadvertidamente o duplicadas claves sobrescriben silenciosamente campos seguridad porque último ganó sin banner advertencia parsers permisivos.

Artículo recorre doce trampas recurrentes porque conversión servidor YAML→JSON modelo OpenAPI espera shapes precisos y cómo inspeccionar transformación Safe Local Tools local navegador antes kubectl apply envía objetos apiserver porque manifiesto internos no deben aparecer pegados formatters nube random.

YAML interfaz humana no lenguaje indulgente máquina

YAML 1.2 admite formas escalares múltiples JSON no—flexibilidad útil prosa configs daña pipelines automatizados porque boolean null numéricos ambiguos según parser edad motor.

Kubernetes acepta YAML cliente convierte JSON servidor: archivo YAML válido sintácticamente puede mapear tipos JSON inesperados produciendo runtime sutil no error inmediato apply—piensa reglas probes recursos mal anidados sidecar sin límites.

Errores estructurales tabs profundidad indentación listas contenedores

YAML prohíbe tab indentación estructural—editores insertan tabs silencioso laptop teclado produciendo found character that cannot start any token aparentemente aleatorio línea parser.

Listas contenedores containers: requieren alineación exacta items - subcampos env: porque indent extra anida readinessProbe objeto equivocado quedando app arranque sin health checks crees aplicaste.

Arregla via .editorconfig spaces-only pre-commit grep tabs *.yaml falla PR porque review human ojo fatiga pierde depth visual archivos 2000 líneas monolíticos.

Escalares sin comillas que mutan boolean null octal legado

Valor off no puede interpretarse falso según parser—quote explícito value: "off" evita sorpresa variables entorno debug supuestamente string interpretadas boolean.

Valores numéricos con ceros iniciales peligro engines viejos interpretan octal—prefiere strings explícitas cantidades recursos 500m 512Mi porque Kubernetes espera strings cantidades no floats JSON.

env:
  - name: DEBUG
    value: off   # puede volverse false en algunos parsers

Claves duplicadas plantillas Helm sin render bloques multilínea

Algunos cargadores YAML ante claves repetidas aplican último valor ganador sin gritar porque creías tener imagePullPolicy: Always pero duplicados sombrear silenciosa versión inicial.

Copy-paste charts Helm dejando {{ .Values.foo }} sin helm template rompe apply porque literales llaves no son Kubernetes válido o campos desconocidos.

Scripts multilínea args: requieren bloques | > porque : internos rompen parsing si no citados cuidadosamente.

CI debe kubectl apply --dry-run=server contra versión cluster target porque CRDs divergen staging producción aceptan shapes distintos APIs beta.

Secretos plano git --- documentos mezclados cantidades string

Secretos base64 en repositorio aun "funciona" localmente es incidente gobernanza esperando scanners—usa SealedSecrets SOPS operadores externos nunca datos prod crudos git.

Separadores --- múltiples documentos ausentes fusionan recursos accidentalmente porque parser une objetos contiguos confusa revisiones diff.

Cantidades CPU memoria deben strings regex Kubernetes—float JSON inválido scheduling ignora límites silenciosamente peligroso bursty workloads.

Anclas YAML JSON puro no entiende conversión revela supuestos ocultos

Referencias &id *id no existen JSON—convertidores expanden rechazan inconsistentemente porque roundtrip pierde intención—duplica explícito manifests committed salvo plantillas locales effimeras.

Convertir JSON temporal ayuda auditar la estructura anidada real que llegará al apiserver porque el JSON elimina comentarios y resalta mejor duplicados que algunos pipelines YAML toleran antes de llegar errores más claros.

Safe Local Tools convierte YAML ↔ JSON dentro del navegador cuando tus políticas vetan lanzar manifests internos a formateadores SaaS externos: tus datos pueden quedar en equipo local dentro del marco de cumplimiento acordado.

Flujo sano antes apply: lint kubeconform dry-run porque ChatGPT YAML alucina apiVersion

yamllint señala problemas rápidamente de sangría y algunos errores triviales antes del merge; kubeconform compara tus manifiestos con los esquemas OpenAPI y se acerca mucho mejor a los rechazos que verá apiserver porque un YAML sintácticamente elegante igualmente puede producir objeto con forma rechazada para ese recurso concreto.

Los modelos de lenguaje suelen producir combinaciones contradictorias de apiVersion y kind o sangrías erráticas: la velocidad de generación textual no compensa ejecutar mismas barreras automatizadas y revisiones humanas que ya tenías porque kubectl real sea la fuente verdaderamente obligatoria.

Este ejemplo de trabajo CI muestra la idea (ajústalo a tus versiones y cluster): ejecuta primero yamllint -c .yamllint manifest/ y luego kubeconform -kubernetes-version 1.29.0 manifest/ para bloquear regresiones estructurales grandes antes del merge cuando nadie tiene energía leer ficheros gigantes línea línea ya de madrugada.

Kustomize estratégicos JSON patch drift multi-cluster porque YAML errores predicibles

Renderiza kustomize build y explora conversión JSON antes del diff porque merges estratégicos pueden aplicar $patch delete donde nadie esperaba borrar—quieres conocer objeto exactamente como lo recibe apiserver porque tipos sutiles en Ingress o selección etiquetas red profundísima pueden servir falsos certs por default sin que kubectl apply rechace la forma YAML.

Políticas seguridad revisar privileged: true hostPath wildcard RBAC porque YAML distribuye permisos peligrosos igual código aplicación porque merges infra.

Safe Local Tools enfatiza convertir navegador local porque manifests internos contienen IP espacios nombres sensibles: incluso evitar sólo esa subida rápido reduce probabilidad pérdidas accidentales ticketing externo, aunque revisiones formales igualmente mandatorias equipo human sigue igual.

Las averías habituales con YAML en Kubernetes rara vez provienen de magia oscura: combinan tabuladores con espacios, valores ambiguos que el cargador fuerza como boolean sin que el equipo lo note al vuelo, claves repetidas donde gana sin aviso la última entrada o Helm sin ejecutar "helm template". Eso aumenta el estrés de guardia porque apiserver devuelve fallos muy profundos en objetos anidados que llegan muy tarde a la vista humana.

Antes de culpar sólo a kubectl, traduce temporalmente tu manifiesto a JSON y revisa la forma que llegará tras la conversión porque es la cara que apiserver espera mediante el modelo JSON/OpenAPI: ahí aparecen rápido anidaciones equivocadas o tipos sospechosos que el archivo YAML bien coloreado enmascaraba antes.

Haz ese bucle usando Safe Local Tools en el navegador pulsando «Probar convertidor YAML ↔ JSON →» para no mandar internals confidenciales a páginas de formateado improvisadas mientras madrugadores deben moverse rápido.