Valida YAML de Kubernetes sin errores: guía completa

Has pasado dos horas depurando por qué tu despliegue de Kubernetes no arranca, solo para descubrir que es una simple sangría mal ubicada en tu manifiesto YAML. Todos hemos estado ahí, y es frustrante cada vez.

Conoce a YF-kun 🤖 — ¡Tu guía amigable de YAMLforge! A lo largo de este artículo, YF-kun aparecerá con consejos útiles, advertencias sobre errores comunes y alguna observación ingeniosa. ¡Piensa en él como ese amigo desarrollador experimentado que siempre te respalda!

😅 YF-kun: Pues mira, esto me volvió loco al principio, la verdad.

😅 YF-kun: Pues mira, una vez pasé tres horas buscando un problema en un despliegue. Resulta que tenía tabuladores mezclados con espacios en mi YAML. Los dioses de Kubernetes no quedaron nada contentos ese día, ¿sabes?

¿Qué es un validador YAML de Kubernetes?

Un validador YAML de Kubernetes revisa sus archivos de manifiesto en busca de errores antes de desplegarlos en su clúster. Detecta tres tipos principales de problemas:

Errores de sintaxis – Estructura YAML inválida como sangría incorrecta, dos puntos faltantes o listas mal formadas. Estos rompen completamente el analizador YAML.

Violaciones de esquema – YAML válido que no coincide con las especificaciones de la API de Kubernetes. Por ejemplo, usar replicas: "3" (cadena) en lugar de replicas: 3 (entero), o escribir mal nombres de campos como contianers en lugar de containers.

Errores lógicos – Configuraciones técnicamente válidas que no funcionarán en la práctica, como hacer referencia a un ConfigMap que no existe o solicitar más recursos de los que sus nodos pueden proporcionar.

La validación ocurre en diferentes etapas: durante el desarrollo en su editor, en pipelines de CI/CD antes del despliegue, o justo antes de aplicar manifiestos con kubectl. Cuanto antes detecte los errores, menos tiempo perderá depurando.

🤔 YF-kun: Por cierto, dato curioso: la API de Kubernetes tiene más de 50 tipos de recursos diferentes, cada uno con cientos de campos posibles. Por eso la validación automatizada es esencial, nadie puede memorizar todos esos esquemas.

Tipos de validadores YAML de Kubernetes

Validación integrada con kubectl

Kubernetes incluye validación básica a través de kubectl. Cuando ejecuta kubectl apply o kubectl create, verifica su YAML contra el esquema del servidor API.

# Validación dry-run sin aplicar cambios
kubectl apply --dry-run=client -f deployment.yaml

# Validación del lado del servidor (verifica contra el clúster real)
kubectl apply --dry-run=server -f deployment.yaml

La bandera --dry-run=client valida sintaxis y esquema localmente, mientras que --dry-run=server envía su manifiesto al servidor API para validación sin crear recursos realmente.

💡 YF-kun: Mira, un consejito: siempre usa --dry-run=server cuando sea posible. Detecta problemas que la validación del lado del cliente pasa por alto, como depreciaciones de versiones de API específicas de tu versión de clúster.

Herramientas de análisis estático

Los analizadores estáticos revisan sus archivos YAML sin conectarse a un clúster de Kubernetes. Las opciones populares incluyen:

kubeval – Valida manifiestos contra esquemas JSON de Kubernetes. Rápido y ligero, perfecto para pipelines de CI/CD.

kubeval deployment.yaml

kubeconform – Una alternativa más rápida y moderna a kubeval con mejor soporte de esquemas.

kubeconform deployment.yaml

kube-score – Va más allá de la validación para proporcionar recomendaciones de mejores prácticas y verificaciones de seguridad.

kube-score score deployment.yaml

Estas herramientas funcionan sin conexión y se integran fácilmente en flujos de trabajo automatizados. Son más rápidas que la validación del lado del servidor porque no necesitan acceso al clúster.

⚠️ YF-kun: ¡Ojo con esto! Los validadores estáticos solo conocen los recursos estándar de Kubernetes. Si está usando Custom Resource Definitions (CRDs), necesitará herramientas que soporten esquemas personalizados o volver a la validación del lado del servidor.

Integraciones de IDE y editores

Los editores de código modernos proporcionan validación YAML en tiempo real mientras escribe:

VS Code con la extensión de Kubernetes muestra errores en línea y autocompletado para campos de Kubernetes. Valida contra esquemas y resalta problemas inmediatamente.

IntelliJ IDEA y GoLand tienen soporte integrado de Kubernetes con validación de esquemas y autocompletado inteligente de código.

Los usuarios de Vim y Neovim pueden instalar complementos como vim-kubernetes con soporte del Language Server Protocol (LSP) para validación.

La validación en tiempo real detecta errores antes de que siquiera guarde el archivo, reduciendo dramáticamente su ciclo de depuración.

🚀 YF-kun: Cuando le pilles el truco: configura tu editor para ejecutar kube-score al guardar. Detectarás tanto errores de validación COMO violaciones de mejores prácticas sin salir de tu IDE.

Errores comunes de YAML que detectan los validadores de Kubernetes

Errores de sangría

YAML es notoriamente exigente con la sangría. Los manifiestos de Kubernetes deben usar espaciado consistente: mezclar tabuladores y espacios causa fallos de análisis.

# ❌ INCORRECTO - Sangría inconsistente
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
   replicas: 3  # 3 espacios
  selector:     # 2 espacios
    matchLabels:
      app: myapp

# ✅ CORRECTO - Sangría consistente de 2 espacios
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp

⚠️ YF-kun: ¡Ojo con esto! Configura tu editor para mostrar caracteres de espacio en blanco y convertir tabuladores a espacios automáticamente. Créeme, te ahorrará horas de frustración.

El problema de Noruega en Kubernetes

Aquí hay un error sutil que atrapa incluso a desarrolladores experimentados. YAML 1.1 trata ciertos códigos de país como booleanos:

apiVersion: v1
kind: ConfigMap
metadata:
  name: countries
data:
  norway: NO     # ¡Se convierte en false!
  yes_option: YES  # ¡Se convierte en true!
  canada: CA     # Se mantiene como cadena

La mayoría de los analizadores YAML convierten NO, YES, ON y OFF a booleanos. En los ConfigMaps de Kubernetes, esto corrompe sus datos:

{
  "data": {
    "norway": false,
    "yes_option": true,
    "canada": "CA"
  }
}

⚠️ YF-kun: ¡Ojo con esto! Este es el infame "Problema de Noruega". Siempre entrecomilla valores que podrían interpretarse como booleanos: norway: "NO". YAMLforge detecta automáticamente y preserva estos valores como cadenas cuando está convirtiendo o validando YAML.

Discrepancias de tipos

Kubernetes espera tipos de datos específicos para cada campo. Un error común es usar cadenas donde se requieren enteros:

# ❌ INCORRECTO - replicas debe ser entero, no cadena
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: "3"  # Tipo cadena
  template:
    spec:
      containers:
      - name: app
        resources:
          requests:
            memory: "128Mi"
            cpu: "500m"  # Esto es correcto - Los valores de CPU son cadenas

# ✅ CORRECTO - Tipos apropiados
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 3  # Tipo entero
  template:
    spec:
      containers:
      - name: app
        resources:
          requests:
            memory: "128Mi"
            cpu: "500m"

Los validadores detectan estas discrepancias de tipos antes del despliegue. Algunos campos como cpu y memory sí requieren cadenas porque incluyen unidades (500m, 128Mi).

💡 YF-kun: Mira, un consejito: si está convirtiendo entre YAML y JSON con frecuencia, use una herramienta que preserve los tipos correctamente. YAMLforge mantiene los tipos entero, cadena y booleano apropiados durante la conversión.

Campos requeridos faltantes

Cada recurso de Kubernetes tiene campos requeridos. Los validadores detectan esto inmediatamente:

# ❌ INCORRECTO - Faltan campos requeridos
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: app
        image: nginx:latest
# Faltan: spec.selector y spec.template.metadata.labels

# ✅ CORRECTO - Todos los campos requeridos presentes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: nginx:latest

El selector.matchLabels debe coincidir exactamente con template.metadata.labels, o su Deployment no gestionará ningún Pod.

Validación de YAML en pipelines de CI/CD

Integrar la validación en su pipeline de integración continua detecta errores antes de que lleguen a producción.

Ejemplo de GitHub Actions

name: Validate Kubernetes Manifests

on:
  pull_request:
    paths:
      - 'k8s/**/*.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install kubeconform
        run: |
          wget https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz
          tar xf kubeconform-linux-amd64.tar.gz
          sudo mv kubeconform /usr/local/bin/
      
      - name: Validate manifests
        run: |
          kubeconform -summary k8s/**/*.yaml

Este flujo de trabajo se ejecuta en cada pull request, validando todos los archivos YAML en el directorio k8s/ antes de fusionar.

🚀 YF-kun: Cuando le pilles el truco: agrega kube-score a tu pipeline también. Aplicará mejores prácticas como límites de recursos, contextos de seguridad y configuraciones de sondas automáticamente.

Ejemplo de GitLab CI

validate-k8s:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -L https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz | tar xz
    - mv kubeconform /usr/local/bin/
  script:
    - kubeconform -summary manifests/**/*.yaml
  only:
    changes:
      - manifests/**/*.yaml

Hooks de pre-commit

Para retroalimentación aún más rápida, valide YAML localmente antes de hacer commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: check-yaml
        args: ['--unsafe']  # Permite etiquetas personalizadas
  
  - repo: local
    hooks:
      - id: kubeconform
        name: Validate Kubernetes manifests
        entry: kubeconform
        language: system
        files: \.yaml$

Instale con pre-commit install, y la validación se ejecuta automáticamente en git commit.

Técnicas avanzadas de validación

Aplicación de políticas con OPA

Open Policy Agent (OPA) le permite definir reglas de validación personalizadas más allá de los esquemas estándar de Kubernetes. Por ejemplo, aplicar que todos los contenedores deben tener límites de recursos:

package kubernetes.admission

deny[msg] {
  input.request.kind.kind == "Deployment"
  container := input.request.object.spec.template.spec.containers[_]
  not container.resources.limits
  msg := sprintf("Container '%s' must have resource limits", [container.name])
}

OPA se integra con controladores de admisión para aplicar políticas en tiempo de despliegue.

🎯 YF-kun: Lo clave es: la validación con OPA detecta problemas de seguridad y violaciones de políticas que los validadores estándar pasan por alto. Es esencial para clústeres de producción con requisitos de cumplimiento.

Validación de recursos personalizados

Si está usando Custom Resource Definitions (CRDs), los validadores estándar no conocerán sus esquemas personalizados. Soluciones:

1. Validación del lado del servidor – Use kubectl --dry-run=server para validar contra los CRDs instalados en su clúster
2. kubeconform con esquemas CRD – Extraiga esquemas CRD y proporciónelos a kubeconform
3. Validación de operador – Muchos operadores incluyen webhooks de validación que verifican recursos personalizados

# Extraer esquemas CRD para validación sin conexión
kubectl get crds -o json | \
  jq '.items[] | .spec.versions[].schema.openAPIV3Schema' \
  > custom-schemas/

# Validar con esquemas personalizados
kubeconform -schema-location default \
  -schema-location 'custom-schemas/{{ .ResourceKind }}.json' \
  my-custom-resource.yaml

Consideraciones de seguridad

La validación no se trata solo de sintaxis, también de seguridad. Busque herramientas que verifiquen:

• Contenedores privilegiados – Ejecutándose como root o con capacidades elevadas
• Montajes de rutas de host – Acceso directo a sistemas de archivos de nodos
• Contextos de seguridad faltantes – Sin políticas o contextos de seguridad de pods definidos
• Secretos en texto plano – Datos sensibles expuestos en manifiestos
• APIs depreciadas – Uso de versiones de API que serán eliminadas

Herramientas como kube-score, kubesec y Polaris se especializan en validación de seguridad.

⚠️ YF-kun: ¡Ojo con esto! Nunca haga commit de secretos reales en sus archivos YAML, ni siquiera en repositorios privados. Use Kubernetes Secrets, administradores de secretos externos o herramientas como Sealed Secrets en su lugar.

Privacidad y procesamiento local

Cuando trabaja con manifiestos de Kubernetes, a menudo maneja datos de configuración sensibles: cadenas de conexión de bases de datos, endpoints de API, límites de recursos que revelan la capacidad de su infraestructura.

Si necesita convertir o validar archivos YAML que contienen datos sensibles:

• Use herramientas del lado del cliente – Validadores como kubeval y kubeconform se ejecutan localmente
• Evite convertidores en línea – Muchas herramientas YAML basadas en web suben sus datos a servidores
• Procese en el navegador – Herramientas como YAMLforge procesan todo del lado del cliente: sus datos nunca salen de su dispositivo

🎯 YF-kun: Lo clave es: cuando convierta configuraciones de Kubernetes a JSON para procesamiento o validación, use herramientas que funcionen completamente en su navegador. YAMLforge procesa todo del lado del cliente, preserva su sangría y comentarios, y maneja automáticamente el Problema de Noruega, ¡todo sin subir nada!

🎉 YF-kun: ¡Listo! try it out at YAMLforge.dev!

Preguntas frecuentes

¿Cuál es la diferencia entre validación del lado del cliente y del servidor?

La validación del lado del cliente (kubectl --dry-run=client) verifica su YAML contra esquemas genéricos de Kubernetes localmente. La validación del lado del servidor (kubectl --dry-run=server) envía su manifiesto a su clúster real, que lo verifica contra su versión específica de Kubernetes, CRDs instalados y webhooks de admisión. La del servidor es más precisa pero requiere acceso al clúster.

¿Puedo validar charts de Helm?

Sí, pero necesita renderizarlos primero. Use helm template para generar los manifiestos reales de Kubernetes, luego valide esos:

helm template my-chart ./chart/ | kubeconform -summary

¿Los validadores funcionan con Kustomize?

Absolutamente. Construya sus overlays de Kustomize primero, luego valide:

kustomize build overlays/production | kubeconform -summary

¿Por qué mi YAML pasa la validación pero falla al desplegar?

La validación verifica sintaxis y esquema, pero no puede detectar todos los errores lógicos. Problemas comunes incluyen hacer referencia a recursos que no existen (ConfigMaps, Secrets), solicitar más recursos de los disponibles o conflictos de puertos. La validación del lado del servidor detecta más de estos, pero algunos solo aparecen durante el despliegue real.

¿Debo validar en mi editor, CI/CD o ambos?

¡Ambos! La validación en el editor da retroalimentación inmediata durante el desarrollo. La validación de CI/CD asegura que nada roto se fusione. Piense en la validación del editor como corrección ortográfica mientras escribe, y CI/CD como la revisión final antes de publicar.

¿Cómo manejo el Problema de Noruega en ConfigMaps de Kubernetes?

Siempre entrecomille valores que parezcan booleanos: country: "NO" en lugar de country: NO. Al convertir YAML a otros formatos, use herramientas que preserven los tipos de cadena correctamente. YAMLforge detecta automáticamente estos casos y los mantiene como cadenas.

¿Listo para empezar? Esto es lo que aprendiste:

• ✅ Qué verifican los validadores YAML de Kubernetes y por qué son esenciales
• ✅ Cómo usar kubectl, kubeval, kubeconform y otras herramientas de validación
• ✅ Errores comunes como el Problema de Noruega, errores de sangría y discrepancias de tipos
• ✅ Cómo integrar validación en pipelines de CI/CD y hooks de pre-commit
• ✅ Técnicas avanzadas con políticas OPA y validación de CRD
• ✅ Consideraciones de seguridad y mejores prácticas de privacidad

🎉 YF-kun: ¡Lo tienes! Comienza con kubectl --dry-run=server para verificaciones rápidas, luego agrega kubeconform a tu pipeline de CI/CD. Y cuando necesites convertir o procesar configuraciones YAML sensibles, dirígete a YAMLforge.dev: maneja todo del lado del cliente con 10 conversiones gratuitas diarias, sin registro requerido. ¡Ve y construye algo increíble!