Solución de problemas de Helm

​

Comandos generales de diagnóstico

# List all Helm releases in the midaz namespace
helm list -n midaz

# Check the status of a specific release
helm status midaz -n midaz

# List all pods and their current state
kubectl get pods -n midaz

# Get events for the namespace (useful for spotting recent failures)
kubectl get events -n midaz --sort-by='.lastTimestamp'

# Describe a specific pod (replace <pod-name> with the actual name)
kubectl describe pod <pod-name> -n midaz

# Tail logs for a pod
kubectl logs <pod-name> -n midaz --tail=100

# Follow logs in real time
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 insuficientes en los nodos. El scheduler no puede encontrar un nodo que satisfaga los resource requests 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 agrega más nodos al cluster.
• PersistentVolumeClaim sin vincular. 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 haya una StorageClass disponible y que sea la predeterminada. Consulta PVC atascado en Pending más abajo.
• Node selector o afinidad que no coinciden. El pod requiere una etiqueta de nodo específica que ningún nodo del cluster tiene. Revisa los ajustes de nodeSelector o affinity en tu values.yaml y verifica que tus nodos tienen 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 registry. Inspecciona el paquete del chart seleccionado y compara ledger.image.tag con sus metadatos y values. La página de versiones del chart de Midaz registra el valor predeterminado auditado.
• El registry privado requiere autenticación. El cluster no puede descargar imágenes sin credenciales. Crea un image pull secret y referéncialo 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
  
• Falta imagePullSecrets. El secret existe pero la configuración del componente no lo referencia. Define imagePullSecrets para 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 ausentes. Falta una clave de configuración obligatoria o tiene un valor incorrecto. Revisa los logs en busca de mensajes como missing env var, invalid config o similares. Revisa la sección configmap de tu values.yaml.
• Falta un Secret de Kubernetes. 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 con Helm.
• Credenciales de base de datos incorrectas. El servicio no puede autenticarse con PostgreSQL, MongoDB o Redis. Revisa los logs en busca de authentication failed o connection refused. Verifica la sección secrets en tu values.yaml y confirma que las credenciales coinciden con las que usaste al provisionar las bases de datos.
• OOMKilled. El contenedor superó su límite de memoria y el kernel lo terminó.
  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 Desalojo de pods / OOMKilled más abajo.

​

Timeout de instalación de Helm

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'

• Descargas de imagen lentas. 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 que fallan. Un init container (por ejemplo, el Job de bootstrap de la base de datos) se cuelga o reintenta. Revisa los logs del init container:
  kubectl logs <pod-name> -n midaz -c <init-container-name>
  
• Probes de readiness que fallan. El pod se ejecuta pero no pasa su verificación de readiness, así que Helm espera indefinidamente. Describe el pod y mira las secciones Conditions y Events. Puedes necesitar aumentar initialDelaySeconds en los ajustes de tu probe de readiness, o investigar por qué el servicio no está sano al arrancar.

​

Servicios inalcanzables

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 controller no lo toma. Verifica que ingress.className coincide con la clase del ingress controller que instalaste:
  kubectl get ingressclass
  
  Revisa también que el pod del ingress controller se ejecuta:
  kubectl get pods -n ingress-nginx
  
• El DNS no apunta al load balancer. El hostname de tu Ingress no resuelve a la IP externa del controller. Obtén la IP externa y compárala con tu registro de DNS:
  kubectl get svc -n ingress-nginx
  
• Configuración incorrecta de TLS. Un secret de TLS ausente o vencido hace que el ingress falle en silencio. Verifica que el secret existe y que no está vencido:
  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

• No hay StorageClass predeterminada. El cluster no tiene una StorageClass predeterminada.
  kubectl get storageclass
  
  Si ninguna muestra (default), crea una StorageClass o define una explícitamente en tu values.yaml para la dependencia afectada (por ejemplo, postgresql.primary.persistence.storageClass).
• Modo de acceso incorrecto. La StorageClass no admite el modo de acceso que solicita el PVC (por ejemplo, ReadWriteMany en un driver de almacenamiento que solo admite ReadWriteOnce). Revisa la sección Events de kubectl describe pvc. Ajusta accessModes en tu values.yaml para que coincida con lo que admite tu StorageClass.
• El modo de vinculación de volumen es WaitForFirstConsumer. Algunas StorageClasses usan vinculación diferida. El PVC permanece en Pending hasta que se programa un pod que lo consume. Este es el comportamiento normal. Espera a que se programe el pod.

​

Desalojo de pods / 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 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: Los valores predeterminados del chart son requests: 256Mi / 1500m y limits: 512Mi / 2000m. Tu override los reemplaza, así que trata los valores predeterminados como la base de dimensionamiento. Define el límite de memoria por encima del predeterminado cuando el contenedor sufre OOMKilled:
  ledger:
    resources:
      requests:
        memory: "512Mi"
        cpu: "1500m"
      limits:
        memory: "1Gi"
        cpu: "2000m"
  
• Nodo con presión de memoria. El nodo mismo está bajo presión y el kubelet desaloja los pods de menor prioridad. Revisa las condiciones del nodo:
  kubectl describe node <node-name> | grep -A5 Conditions
  
  Considera agregar nodos o habilitar el cluster autoscaler. También puedes definir PriorityClass en los pods de Midaz para protegerlos del desalojo.

​

Definiciones de RabbitMQ sin cargar

kubectl get pods -n midaz | grep rabbit
kubectl logs <rabbitmq-pod-name> -n midaz --tail=100
# Check if the bootstrap job ran
kubectl get jobs -n midaz
kubectl logs job/midaz-bootstrap-rabbitmq -n midaz

• Al RabbitMQ externo le falta load_definitions.json. Cuando usas una instancia externa de RabbitMQ, las colas, los exchanges y los 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 está en charts/midaz/files/rabbitmq/load_definitions.json en el repositorio de Helm.
• El Job de bootstrap falló en silencio. El job se ejecutó pero encontró un error (credenciales incorrectas, timeout de red, puerto incorrecto).
  kubectl logs job/midaz-bootstrap-rabbitmq -n midaz
  
  Verifica las credenciales de rabbitmqAdminLogin y que el puerto de gestión (predeterminado 15672) es alcanzable desde dentro del cluster.

​

Recursos relacionados

• Desplegar Midaz con Helm: guía de instalación inicial
• Actualizar Midaz y los plugins con Helm: procedimientos de actualización y rollback
• Actualizar Helm: cambios incompatibles y rutas de migración entre versiones mayores
• Compatibilidad de versiones del chart de Midaz: metadatos actuales del chart y de la aplicación
• Repositorio de Helm: código fuente y notas de release