Guía de actualización de Helm para Midaz

Actualiza tu despliegue Helm de Midaz — inicio rápido, los releases con cambios incompatibles entre v5 y v8, actualización de plugins y verificaciones posteriores.

Esta guía te lleva por la actualización de tu despliegue Helm de Midaz a la línea actual del chart, v8.x.

Encontrarás un inicio rápido para operadores experimentados, los releases con cambios incompatibles que no debes saltarte a ciegas, la actualización de plugins y las verificaciones posteriores.

¿Necesitas repasar la instalación de Midaz con Helm? Consulta la guía Instalación de Midaz con Helm antes de comenzar la actualización.

​

Inicio rápido

---

​

1. Verifica los prerrequisitos

• Helm v3.8+ instalado y disponible (helm version) — necesario para el soporte de registries OCI.
• Clúster de Kubernetes v1.20+ en ejecución.
• Copia de seguridad de tus bases de datos y de tu archivo de values.

​

2. Identifica tu versión actual

helm list -n midaz

La columna CHART muestra la versión de tu chart (por ejemplo, midaz-helm-8.6.0).

​

3. Ejecuta el comando de actualización

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version-objetivo> \
  -n midaz \
  -f tus-values.yaml

​

4. Verifica la actualización

helm list -n midaz
kubectl get pods -n midaz

​

Compatibilidad de versiones

---

Componente	Requisito
Kubernetes	1.20+
Helm	3.8+ (soporte OCI)
PostgreSQL	13+
MongoDB	4.4+
Valkey	7.x

El chart incluye PostgreSQL, MongoDB, RabbitMQ y Valkey como dependencias de subcharts. Apunta el chart a tus propias instancias gestionadas deshabilitando cada dependencia (postgresql.enabled: false, etc.) — consulta Values de producción.

​

Releases con cambios incompatibles que debes considerar

---

No saltes varias versiones mayores en un solo helm upgrade. Lee la nota de actualización del release en el repositorio del chart (charts/midaz/docs/UPGRADE-*.md) para cada versión mayor entre tu chart actual y tu objetivo.

Release del chart	Qué cambió
v5.0.0	Se eliminaron los componentes Console y NGINX. Con ellos se eliminaron también los templates del stack de observabilidad de Grafana.
v7.0.0	Los servicios onboarding y transaction se eliminaron por completo — toda su funcionalidad se consolidó en el único servicio ledger. Los helpers de templates de los servicios antiguos ya no existen.
v8.4.0	El subchart otel-collector-lerian ya no se instala. La clave solo inyecta variables de entorno de OTEL y su esquema acepta únicamente enabled; las claves heredadas (external, extraEnvs, exporters, opentelemetry-collector) ahora fallan la validación al actualizar.

Si aún ejecutas un chart v4.x o v5.x, migra siguiendo las rutas de Descripción general de migraciones en lugar de actualizar directamente a v8.

​

Actualización del core de Midaz

---

Al actualizar Midaz o cualquier plugin, actualiza siempre el chart de Helm correspondiente.

Actualizar versiones de aplicación sin actualizar el chart de Helm puede provocar fallos de despliegue o entornos inconsistentes.

​

1. Consulta las versiones disponibles

Los charts se distribuyen solo como artefactos OCI: no hay un índice de repositorio Helm que consultar, por lo que helm search repo no funciona aquí. Explora los tags de release para descubrir versiones y luego inspecciona una en concreto:

helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version>

O revisa los tags de release:

• Visita https://github.com/LerianStudio/helm/tags
• Filtra por el prefijo midaz-v

​

2. Revisa los cambios antes de actualizar

Compara tus values actuales con los valores por defecto del chart objetivo:

helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version-objetivo> > new-defaults.yaml

Luego renderiza la actualización sin aplicarla:

helm template midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version-objetivo> \
  -n midaz \
  -f tus-values.yaml

Una violación del esquema (por ejemplo, una clave heredada de otel-collector-lerian) falla aquí en lugar de a mitad de la actualización.

​

3. Ejecuta la actualización

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version-objetivo> \
  -n midaz \
  -f tus-values.yaml \
  --wait --timeout 10m

Pasa siempre tus values con -f. Sin ello, Helm no reutiliza nada de tu configuración anterior y el release vuelve a los valores por defecto del chart.

​

4. Verifica la actualización

• Comprueba el estado del release

helm list -n midaz

• Verifica que los pods estén en ejecución

kubectl get pods -n midaz

• Revisa los logs de los pods en busca de errores

kubectl logs -n midaz deployment/midaz-ledger --tail=50

Si ejecutas CRM (crm.enabled: true — está deshabilitado por defecto):

kubectl logs -n midaz deployment/midaz-crm --tail=50

Todos los pods deben mostrar estado Running y sus contenedores listos.

midaz-ledger es el único Deployment de aplicación que el chart crea por defecto; midaz-crm se agrega cuando crm.enabled: true. midaz-onboarding y midaz-transaction ya no existen desde el chart v7.0.0.

​

Actualización de plugins

---

Actualiza siempre el core de Midaz antes de actualizar los plugins. Los plugins dependen de las APIs del core.

Los plugins son releases independientes y se instalan en su propio namespace, midaz-plugins. Consulta los tags de release del propio plugin en https://github.com/LerianStudio/helm/tags para conocer la versión actual.

​

CRM

CRM forma parte del chart de Midaz — no hay un release de CRM aparte que actualizar. Si lo habilitas (crm.enabled: true), verifica sus pods tras la actualización del core:

kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm

​

Fees Engine

helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <version-objetivo> \
  -n midaz-plugins \
  -f plugin-fees-values-backup.yaml

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees

​

Pix

helm upgrade plugin-br-pix-direct-jd oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
  --version <version-objetivo> \
  -n midaz-plugins \
  -f plugin-pix-values-backup.yaml

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd

El chart etiqueta cada workload con el conjunto de labels app.kubernetes.io/*. Un selector como -l app=midaz-crm no coincide con nada.