> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de problemas de Helm

> Diagnostica y resuelve los problemas comunes al desplegar u operar Midaz en Kubernetes — fallos de pods, errores de ingress y conflictos de dependencias.

Esta guía te ayuda a diagnosticar y resolver los problemas más comunes al desplegar u operar Midaz en Kubernetes con Helm. Cada sección cubre un síntoma específico, los comandos de diagnóstico para investigarlo y los pasos para resolverlo.

## Comandos generales de diagnóstico

***

Comienza con estos comandos para obtener una visión general del estado de tu despliegue antes de profundizar en problemas específicos.

```bash theme={null}
# 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

***

**Síntoma:** Uno o más pods permanecen en estado `Pending` y nunca arrancan.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'
kubectl top nodes
```

**Causas comunes y soluciones:**

* **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`.

  ```bash theme={null}
  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](#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:

  ```bash theme={null}
  kubectl get nodes --show-labels
  ```

***

## ImagePullBackOff

***

**Síntoma:** Los pods muestran estado `ImagePullBackOff` o `ErrImagePull`.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp' | grep -i image
```

**Causas comunes y soluciones:**

* **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](/es/platform/helm/helm-version-compatibility).

* **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`:

  ```bash theme={null}
  kubectl create secret docker-registry regcred \
    --docker-server=<registry-url> \
    --docker-username=<username> \
    --docker-password=<password> \
    -n midaz
  ```

  ```yaml theme={null}
  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

***

**Síntoma:** Los pods arrancan y se caen inmediatamente, reiniciándose repetidamente.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl logs <pod-name> -n midaz --previous
kubectl describe pod <pod-name> -n midaz
```

<Tip>
  Usa `--previous` para ver los logs de la última instancia del contenedor caído, no la que está reiniciándose actualmente.
</Tip>

**Causas comunes y soluciones:**

* **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.

  ```bash theme={null}
  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.

  ```bash theme={null}
  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](#evicción-de-pod--oomkilled) más abajo.

***

## Timeout en Helm install

***

**Síntoma:** `helm install` o `helm upgrade` falla con un error de timeout antes de que el release alcance el estado `deployed`.

**Comandos de diagnóstico:**

```bash theme={null}
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'
```

**Causas comunes y soluciones:**

* **Descarga de imágenes lenta** — Las imágenes grandes en una conexión lenta pueden superar el timeout predeterminado. Aumenta el timeout:

  ```bash theme={null}
  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:

  ```bash theme={null}
  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

***

**Síntoma:** Las APIs de Midaz no son accesibles desde fuera del clúster, o los servicios no pueden comunicarse internamente.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get ingress -n midaz
kubectl describe ingress <ingress-name> -n midaz
kubectl get svc -n midaz
kubectl get endpoints -n midaz
```

**Causas comunes y soluciones:**

* **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:

  ```bash theme={null}
  kubectl get ingressclass
  ```

  También verifica que el pod del controlador de ingress esté corriendo:

  ```bash theme={null}
  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:

  ```bash theme={null}
  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:

  ```bash theme={null}
  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:

  ```bash theme={null}
  kubectl get certificate -n midaz
  kubectl describe certificate <cert-name> -n midaz
  ```

***

## PVC atascado en Pending

***

**Síntoma:** Un PersistentVolumeClaim permanece en estado `Pending` y el pod dependiente no puede arrancar.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pvc -n midaz
kubectl describe pvc <pvc-name> -n midaz
kubectl get storageclass
```

**Causas comunes y soluciones:**

* **Sin StorageClass predeterminado** — Ningún StorageClass está marcado como predeterminado en el clúster.

  ```bash theme={null}
  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

***

**Síntoma:** Los pods son eviccionados repetidamente o muestran `OOMKilled` en su último estado.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz | grep -A10 "Last State"
kubectl top pods -n midaz
kubectl top nodes
```

**Causas comunes y soluciones:**

* **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`:

  ```yaml theme={null}
  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:

  ```bash theme={null}
  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

***

**Síntoma:** Los servicios de Midaz arrancan pero las transacciones fallan, faltan colas, o los mensajes no se procesan. Los logs pueden mostrar errores de conexión AMQP o exchanges/colas faltantes.

**Comandos de diagnóstico:**

```bash theme={null}
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
```

**Causas comunes y soluciones:**

* **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`:

  ```yaml theme={null}
  global:
    externalRabbitmqDefinitions:
      enabled: true
      connection:
        protocol: "http"
        host: "your-rabbitmq-host"
        port: "15672"
        portAmqp: "5672"
  ```

  O aplica las definiciones manualmente:

  ```bash theme={null}
  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](https://github.com/LerianStudio/midaz-helm).

* **Job de bootstrap fallado silenciosamente** — El job se ejecutó pero encontró un error (credenciales incorrectas, timeout de red, puerto incorrecto).

  ```bash theme={null}
  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](/es/platform/helm/midaz/midaz-installation) — Guía de instalación inicial
* [Actualizar Midaz y plugins con Helm](/es/platform/helm/midaz/midaz-upgrade-guide) — Procedimientos de actualización y rollback
* [Actualización de Helm](/es/platform/helm/midaz/midaz-upgrading-overview) — Cambios importantes y rutas de migración entre versiones mayores
* [Compatibilidad de versiones](/es/platform/helm/helm-version-compatibility) — Tabla de referencia de versiones
* [Repositorio de Helm](https://github.com/LerianStudio/midaz-helm) — Código fuente y notas de versión