Solución de problemas de Helm

​

Comandos generales de diagnóstico

# Listar todos los releases de Helm en el namespace midaz
helm list -n midaz

# Verificar el estado de un release específico
helm status midaz -n midaz

# Listar todos los pods y su estado actual
kubectl get pods -n midaz

# Obtener eventos del namespace (útil para detectar fallas recientes)
kubectl get events -n midaz --sort-by='.lastTimestamp'

# Describir un pod específico (reemplaza <pod-name> con el nombre real)
kubectl describe pod <pod-name> -n midaz

# Ver los últimos logs de un pod
kubectl logs <pod-name> -n midaz --tail=100

# Seguir los logs en tiempo real
kubectl logs <pod-name> -n midaz -f

​

Pods atascados en Pending

kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'
kubectl top nodes

• CPU o memoria insuficiente en los nodos — El scheduler no puede encontrar un nodo que satisfaga las solicitudes de recursos del pod. Revisa la sección Events de kubectl describe pod. Busca mensajes como Insufficient cpu o Insufficient memory. Reduce resources.requests en tu values.yaml o añade más nodos al clúster.
• PersistentVolumeClaim sin enlazar — Un PVC requerido por una dependencia (PostgreSQL, MongoDB, Valkey) está atascado en Pending.
  kubectl get pvc -n midaz
  kubectl describe pvc <pvc-name> -n midaz
  
  Verifica que exista un StorageClass disponible y configurado como predeterminado. Consulta PVC atascado en Pending más abajo.
• Node selector o affinity sin coincidencia — El pod requiere una etiqueta de nodo específica que ningún nodo del clúster tiene. Revisa tu values.yaml para ver la configuración de nodeSelector o affinity, y verifica que los nodos tengan las etiquetas esperadas:
  kubectl get nodes --show-labels
  

​

ImagePullBackOff

kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp' | grep -i image

• Tag de imagen incorrecto — El tag especificado no existe en el registro. Verifica el valor de image.tag en tu values.yaml contra la tabla de compatibilidad de versiones.
• Registro privado requiere autenticación — El clúster no puede descargar imágenes sin credenciales. Crea un secret de imagen y referencíalo en tu values.yaml:
  kubectl create secret docker-registry regcred \
    --docker-server=<registry-url> \
    --docker-username=<username> \
    --docker-password=<password> \
    -n midaz
  
  ledger:
    imagePullSecrets:
      - name: regcred
  
• imagePullSecrets no configurado — El secret existe pero no está referenciado en la configuración del componente. Asegúrate de que imagePullSecrets esté configurado en todos los componentes afectados.

​

CrashLoopBackOff

kubectl get pods -n midaz
kubectl logs <pod-name> -n midaz --previous
kubectl describe pod <pod-name> -n midaz

• Variables de entorno incorrectas o faltantes — Una clave de configuración requerida está ausente o tiene un valor incorrecto. Revisa los logs buscando mensajes como missing env var, invalid config o similares. Revisa la sección configmap de tu values.yaml.
• Secret de Kubernetes faltante — El pod referencia un secret que no existe.
  kubectl get secrets -n midaz
  kubectl describe secret <secret-name> -n midaz
  
  Si el secret no existe, créalo manualmente o vuelve a ejecutar la instalación de Helm.
• Credenciales de base de datos incorrectas — El servicio no puede autenticarse con PostgreSQL, MongoDB o Redis. Revisa los logs buscando authentication failed, connection refused o ECONNREFUSED. Verifica la sección secrets en tu values.yaml y confirma que las credenciales coincidan con las usadas al aprovisionar las bases de datos.
• OOMKilled — El contenedor superó su límite de memoria y fue eliminado por el kernel.
  kubectl describe pod <pod-name> -n midaz | grep -A5 "Last State"
  
  Busca OOMKilled en la sección Last State. Aumenta resources.limits.memory en tu values.yaml. Consulta Evicción de pod / OOMKilled más abajo.

​

Timeout en Helm install

helm status midaz -n midaz
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'

• Descarga de imágenes lenta — Las imágenes grandes en una conexión lenta pueden superar el timeout predeterminado. Aumenta el timeout:
  helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --version <version> \
    -n midaz \
    --create-namespace \
    --timeout 15m
  
• Init containers fallando — Un init container (por ejemplo, el job de bootstrap de base de datos) está colgado o reintentando. Revisa los logs del init container:
  kubectl logs <pod-name> -n midaz -c <init-container-name>
  
• Readiness probes fallando — El pod está corriendo pero no pasa su verificación de readiness, por lo que Helm espera indefinidamente. Describe el pod y revisa las secciones Conditions y Events. Puede que necesites aumentar initialDelaySeconds en la configuración del readiness probe, o investigar por qué el servicio no está saludable al arrancar.

​

Servicios no accesibles

kubectl get ingress -n midaz
kubectl describe ingress <ingress-name> -n midaz
kubectl get svc -n midaz
kubectl get endpoints -n midaz

• Configuración incorrecta del Ingress — El recurso Ingress existe pero el controlador no lo está procesando. Verifica que ingress.className coincida con la clase de tu controlador de ingress instalado:
  kubectl get ingressclass
  
  También verifica que el pod del controlador de ingress esté corriendo:
  kubectl get pods -n ingress-nginx
  
• DNS no apunta al balanceador de carga — El hostname en tu Ingress no resuelve a la IP externa del controlador. Obtén la IP externa y compárala con tu registro DNS:
  kubectl get svc -n ingress-nginx
  
• Configuración TLS incorrecta — Un secret TLS faltante o expirado hace que el ingress falle silenciosamente. Verifica que el secret exista y no haya expirado:
  kubectl get secret <tls-secret-name> -n midaz
  kubectl describe secret <tls-secret-name> -n midaz
  
  Si usas cert-manager, revisa el estado del recurso Certificate:
  kubectl get certificate -n midaz
  kubectl describe certificate <cert-name> -n midaz
  

​

PVC atascado en Pending

kubectl get pvc -n midaz
kubectl describe pvc <pvc-name> -n midaz
kubectl get storageclass

• Sin StorageClass predeterminado — Ningún StorageClass está marcado como predeterminado en el clúster.
  kubectl get storageclass
  
  Si ninguno muestra (default), crea un StorageClass o configura uno explícitamente en tu values.yaml para la dependencia afectada (por ejemplo, postgresql.primary.persistence.storageClass).
• Modo de acceso incorrecto — El StorageClass no soporta el modo de acceso solicitado por el PVC (por ejemplo, ReadWriteMany en un driver de almacenamiento que solo soporta ReadWriteOnce). Revisa la sección Events de kubectl describe pvc. Ajusta accessModes en tu values.yaml para que coincida con lo que soporta tu StorageClass.
• Modo de binding del volumen es WaitForFirstConsumer — Algunos StorageClasses usan binding diferido. El PVC permanecerá en Pending hasta que un pod que lo consuma sea programado. Este es un comportamiento normal; espera a que el pod sea programado.

​

Evicción de pod / OOMKilled

kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz | grep -A10 "Last State"
kubectl top pods -n midaz
kubectl top nodes

• Límites de memoria configurados demasiado bajos — El resources.limits.memory del contenedor está por debajo de lo que el servicio realmente necesita bajo carga. Revisa el uso actual de memoria con kubectl top pods y luego aumenta el límite en tu values.yaml:
  ledger:
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
  
• Nodo bajo presión de memoria — El nodo en sí está bajo presión y el kubelet está eviccionando pods de menor prioridad. Verifica las condiciones del nodo:
  kubectl describe node <node-name> | grep -A5 Conditions
  
  Considera agregar nodos o habilitar el cluster autoscaler. También puedes establecer PriorityClass en los pods de Midaz para protegerlos de la evicción.

​

Definiciones de RabbitMQ no cargadas

kubectl get pods -n midaz | grep rabbit
kubectl logs <rabbitmq-pod-name> -n midaz --tail=100
# Verificar si el job de bootstrap se ejecutó
kubectl get jobs -n midaz
kubectl logs job/<bootstrap-job-name> -n midaz

• RabbitMQ externo sin load_definitions.json — Al usar una instancia externa de RabbitMQ, las colas, exchanges y bindings requeridos no están presentes. Habilita el job de bootstrap en tu values.yaml:
  global:
    externalRabbitmqDefinitions:
      enabled: true
      connection:
        protocol: "http"
        host: "your-rabbitmq-host"
        port: "15672"
        portAmqp: "5672"
  
  O aplica las definiciones manualmente:
  curl -u {user}:{pass} -X POST -H "Content-Type: application/json" \
    -d @load_definitions.json \
    http://{host}:{port}/api/definitions
  
  El archivo load_definitions.json se encuentra en charts/midaz/files/rabbitmq/load_definitions.json en el repositorio de Helm.
• Job de bootstrap fallado silenciosamente — El job se ejecutó pero encontró un error (credenciales incorrectas, timeout de red, puerto incorrecto).
  kubectl logs job/<bootstrap-job-name> -n midaz
  
  Verifica las credenciales de rabbitmqAdminLogin y que el puerto de administración (predeterminado 15672) sea accesible desde dentro del clúster.

​

Recursos relacionados

• Desplegar Midaz con Helm — Guía de instalación inicial
• Actualizar Midaz y plugins con Helm — Procedimientos de actualización y rollback
• Actualización de Helm — Cambios importantes y rutas de migración entre versiones mayores
• Compatibilidad de versiones — Tabla de referencia de versiones
• Repositorio de Helm — Código fuente y notas de versión